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PREFACE 


This manual describes a version of the programming language 
APL developed by the University Computing Center of the 
University of Massachusetts at Amherst. The system described 
here, known as APLUM, was „developed under the direction of James 
H. Burrill, who was responsible for the overall system design, 
planning, and coordination, and who wrote a considerable portion 
of the system. Other programmers on the project included Rick 
Mayforth, who was responsible for system commands, system 
functions, and system variables; Sheldon Gersten, who did work 
on mixed functions and shared variables; Brian Arnold, who 
worked primarily on output, format functions, апа shared 
variables; Jeff Dean, who worked on mixed functions, workspace 
conversion and systen functions; Judy Smith, who wrote inner 
product; and Clark Wiedmann, who worked on function definition, 
the file system, and mixed functions. In addition, Pat Driscoll 
and Wendy Mayfield assisted with documentation. The Raytheon 
Corporation provided assistance with many of the scalar 
functions, as did the Canadian Development Division of Control 
Data Corporation. The project was supported in part by a grant 
from Control Data Corporation. Special thanks are due to the 
entire staff of the University Computing Center for their 
assistance with the APL project. Credit is also due to the 
developers of several other versions of the APL language for the 
features and careful design that guided us in the development of 
APLUM, 


Primary objectives of the design for APLUM were: to achieve 
a very high level of performance on the CDC 5600 and CYBER 
Computers under the KRONOS operating system, to provide a 
flexible file system, to incorporate system functions and 
variables, to provide all system command capabilities to 
user-defined functions, to allow communication with programs in 
other languages, and to allow all workspace areas (including the 
symbol table and file buffors) to change size dynamically 
according to changing needs. The system was also designed with a 
storage management scheme that will enable futuro implemontation 


of arrays of arrays or future extensions to allow functions and 
variables not in use to reside on secondary memory devices, thus 
allowing an almost unlimited workspace size, 


This edition is intended to describe version 2.12 of АРЫМ, 
For information about recent changes, see the APLNEWS workspace 
on the system, This is accessed by typing the APL ‘command [04D 
"sAPLY APLNEWS'. 


This book is arranged as а reference manual and not as a 
teaching manual. The intent is to accurately describe particular 
details of APLUM, but not to teach APL to the novice. Hence the 
reader will find that this book lacks the wealth of examples, 
problems, and exercises that are usually found in а teaching 
manual. | Some previous knowledge of APL is almost essential in 
order to make use of this manual, and the following books are 
recommended as possible introductions to the language: 


APL\360 Primer, Paul Berry, IBM Technical Publications, 
New York, 1969. Covers in detail function definition 
апд many primitive functions and system commands, but 
barely touches on matrices, higher-order arrays, and 
many mixed functions. Recommended for the occasional 
user of APL. 


Handbook of APL Pro: amming, Clark Wiedmann, Petrocelli 
Books,  N.Y., 1974. A comprehensive introduction for 
the more advanced user of APL who will make extensive 
use of the capabilities available. 


Although this reference manual is intended for the reader 
who already has some knowledge of APL, it is recognized that all 
too often programmers are introduced to a new language through a 
reference manual. Consequently, a short introduction has been 
provided so that the following chapters will make some sense to 
the APL novice. The introduction also attempts to emphasize some 
of the more important features of the language to an extent that 
the organization of later chapters does not allow. 


Amherst, 1975 
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Introduction. A Sample Terminal Session 


This short introduction to APL shows a sample terninal 
session from the time of signing on until the time of sicning 
off. This section attempts to emphasize some of the important 
facilities of APL, and attempts to show the dynamic nature of APL 
(which may not be evident from the following chapters). 


SIGUING ON 


The first step is to establish a telephone connection 
between the terminal and the computer. This procedure varies 
sccewhat according to the installation and the equipment used. 
Purther information about telephone numbers, types of terminals 
zhat are supported, accounting procedures, and restrictions 
placed on use of computer resources should be obtained from the 
installation. The following discussion assumes that an acoustic 
coupler will be used and that the terminal is capable of printing 
сле APh symbols (a Selectric ог an ASCII-APL terminal). Other 
terminals, such as a Model 13 Teletype, can be used (see 
Appendix C) but they are much less satisfactory. 


1. Turn on the terminal and the coupler (sometimes one 
switch activates both). Dial the phone number for the 
computer. АЁ nost installations the phone number 
varies according to the type of terminal and the data 


rate to be used. However, at the University of 
Massachusetts a single phone number is used 
(413-545-1600). You should soon hear a high-pitched 


tone indicating the computer has answered the phone. 
Place the telephone hanáset in the acoustic couple. 
Usually, one end of the acoustic coupler is marked 
"cord" to indicate which end of the telephone handset 
should be placed there. It is important to match the 
correct ends. 


АЕ most installations the system will begin to 
= after a pause of a few seconds. However, at the 
rsity of Massachusetts the user must take the 
tiative by typing 1+ and RETURN for a Selectric 
terninai, or } and RETURN for an ASCII-APL terminal. 
These first characters identify the type of terminal 
being used and the čata transmission rate to the TEMPO 
mini-computer that handles communications. Failure to 
use the correct characters to identify the terminal is 
likely to result in failure to communicate. 


А 


3. тһе system will print something like the following: 


75/08/14. 16.14.50. 
UMASS CYBER Th, KRONOS 2.1.7 "Ст. 
USER NUMBER: 


The first line is the current date and time, and the 
second line identifies the installation and version of 
the operating systom in use. Type your user number 
where the system has requested it and press RETURN. 
The system will then request your password. Туре it 
over the blackened squares the computer provides (or 
merely press RETURN if your user number has no 
password). The system responds with something like: 


TERMINAL 22, COR 
RECOVER/SYSTEM: 


4. Type APLUM to begin APL processing if you are 
using an ASCII-APL terminal (e.g., Teletype 38, 
Tektronix 4013, сх Memorex 1240 with APL keyboards). 
At the University of Massachusetts cther terminals that 
print APL characters (e,g., Selectric terminals) may be 
used without special considerations. However, for most 
installations the use of such terminals requires the 
use of APLUM commands of the form APLUM.ZT-COR. бев 
Appendix C and Appendix D for details. The APL system 
will identify itself as follows: 


APLUM2.11 75/08/12. 09.57.22. 
HEN APLWEWS 75/08/06 
CLEAR WS 


The time and date on the top linc indicate when the 
present version of APL was generated, The message YEW 
APLNEWS indicates when a news item about changes in the 
APL system was entered. То access the news item, type 
the command SLOAD'*APL1 APLUEWS'. ‘the message CLEAR WS 
indicates that you have begun with a clear active 
workspace. 


IMMEDIATE EXECUTION MODE 


You can now type APL expressions. What you type is 
evaluated immediately. For oxample, 
345 (You typo this and press RETURN.) 
8 (This is the computer's response.) 


Pressing the RETURN key is your signal to the computer that you 
have finished typing the line. The computer will not process the 
line until you press RETURN. The expressions you type аге 
interpreted as they appear on the paper. This is called the 
principle of visual fidelity, You can space forward or backward 
as much as you please as long as the final appearance of the 
paper is what you intended. If you make a typing mistake you can 
Cancel the line by pressing АТТЫ and RETURN (for a Selectric 
terminal) or ESC (for an ASCII terminal), You can revise the 
line if you have not pressed RETURN. To revise the line, press 
ATTN (fora Selectric terminal) ог LINE FEED (for an ASCII 
terminal) then backspacé until the type element is positioned 
below the left-most character to be corrected. this cancels the 
part of the line directly above and to the right of that 
position. Then type any characters to replace those that were 
removed. 


The following examples show some simple calculations being 
performed. 


2x3 


Note that the APL system indents six spaces before allowing you 
to type, but the system prints its response at the left margin. 
This clearly distinguishes what you type from what the computer 
types. тһе following example shows how arithmetic can be 
performed with several numbezs at the sane time 


21 2396 
2468 
The series of numbers on the right is called a vector. Each 
element of the vector was multiplied by 2. 
Values can be given а name and saved for later use. The 
names are called variables. The process of giving a variable а 
value is called assignment. The following examples show 


assignment of values to variables A and 8. 


Aes. B 
Bea 234 
A+B 

5.8.6.8 7.8 Е.8 


Note that when the result of a calculation is not assigned to a 
variable it is printed. The sum of the elements in a vector can 
be found as follows: 


Be1 234 
+/8 
10 


Any symbols on the keyboard can be used as values if they 
are surrounded by quotes. For example, 


GRADES*" ABADCABAABADB" 


The = symbol can be used to compare values. The result is 1 
where a match is found and 0 otherwise. For example, 


!A' sGRADES 
1010010110100 


The following example shows how а table of comparison values can 
be produced: 


oono 


ocon 
ooon 
nooo 
ooro 


There is one row for each value in 'APCD' and there is one column 
for each value in GRADES. To find the number of A's, B's, C's, 
and D's, add up the 1's in the four rows as follows: 


t/CABOD 
6512 


=GRADES) 


Below is an example of another comparison table using < instead 
of =. Also, instead of using +/ to add the rows as in the last 
example, +# is used to add up the columns. The symbol /, called 
an overstrike, is formed by typing /, backspacing, and then 
typing -. (Actually the two symbols comprising the overstrike 
can be typed in either order.) 

Ved. 08 8.1 4.6 1.2 2.3 4,2 1.6 


s 


ocooor 
eooot. 


3.2 
ae. 
11 
°1 
оо 
оо 


ocon 
союш. 


+202 щ 6 Be. 57) 
110320120 


As shown, this operation classifies each value 


Y according to 


the number of values in 2 4 6 В it exceeded. That is, a value 
between 2 and 4 is in class l, а value between 4 and 6 is in 
class 2, anda value between 6 and 8 is in class 3. A user 


defined function can be written to perform this operation: 


?2-А CLASSIFY B 
12 LL IET! 


The first V signals to the computer that you wish to define а 
function. The first line shows that the function takes two 
arguments (input values) and gives a result. The conputer 
numbered the next line with (11. The 9 at the end indicates you 
have completed typing the lines of the function. The function 
can be used as follows: 
2468 
11040201 
Now it might be interesting to tabulate how many 0's, l's, 2's, 
and so forth were in the last result. An APL function can be 
written to do this but it requires two more APL operations: The 
largest value ina vector V is given by [/¥; and iW gives the 


integers 1 2 3 ... N. We use both of these as follows: 
92-TAB 8 
[AJ о к«а((Т/В)я1) 
[2] яек-1 
Тэ] Zee/ ts -B)8 


748 0101213 
2311 


TAB(2 4 6 8 CLASSIFY V) 
33291 


The following function will give a. cruce histogram of these 
results: 


98-157 B 
[1]  P-f/B 
[2J 2-((Pr1)-1P) e sB 9 


HIST33221 


А neater histogram can be produced by adding another line to the 
HIST function: 


TAIST (Function definition is opened.) 
їз} Ze! П'{2+1) (Another line is added.) 
£] (DI {Display is requested.) 
v 269157 В 
С1] P-/8 


[22 2=(02+2)-1Р)•,58 
[32 2+" 0'{2+1) 
9 
w Y (Definition is closed.) 


Note that to add more to the function you first type у and the 
hame (but not Z+#1S? В). Тһе computer numbered the line (3). 
Typing (0) on the next line caused the computer to list the 
fi'etion. Finally, the 9 was typed to indicate that по more 
lines were to be added. This function can now be used with the 
two others as follows: 


BIST ТАВ 2 4 6 8 CLASSIFY 7 
na 


noo 
000 D 


you can display the names of defined functions and variables as 
shown below: 


DENS 
CLASSIFY BIST ТАВ 


VARS 
A B GRADES К P V 


то save the functions and variables for use at some other 
session, type 


)SAVE MYWORK 


the collection of functions апа variables constitutes а 
тве кессе. Here а workspace named MYWORX was saved. Tt is 
Lafe to save the workspace often if you are changing it in 
OB ser to minimize the amount of work that will be lost in the 
ОРӨПЕ of a serious computer malfunction. (See Chapter 12 for the 
procedure to follow to avoid losing work after a telephone 
Pioconnect or minor computer malfunction) То remove all 
disQtions and variables from the workspace you are now working 
with, type 


CLEAR 
NEW APLNEWS 75/08/08 
CLEAR WS 
ENS 
(No Functions.) 
VARS 
(No variables, ) 


You can retrieve the MYWORK workspace as shown belo 


)LOAD MYWORZ 
MYWORK 75/08/08 
DENS 
CLASSIPY KIST ТАБ 


128228 


To terminate the session and sign off the computer, type )OFF. 


OFF 
4123556 100 OFF, 18.12.07 
4123456 СР 0.012 SEC 


Although this sample session was short and only used a small 
fraction of the APL operations, it illustrates how well adapted 
APL is to experimentation. Programs can easily be developed in 
Small parts and put together to do useful work. The flexibility 
in using functions in new combinations makes many problens much 
easier to solve. Many users of APL begin with the habit (formed 
by familiarity with other computer languages) of writing large 
monolithic programs in one piece. It should be evident that the 
modular approach illustrated above is better. 


Chapter 1, User-Defined Functions 


Function definition mode allows the user to enter function 
lines one at a time, renove lines, change lines, insert lines, or 
display the function. In function definition mode, АРІ 
statements entered are not executed or checked for errors, nor 
are systen commands executed, Most errors will be detected when 
the statement is executed for the first time. System commands 
are illegal in the body of a function. 


CREATING A FUNCTION 

To enter function definition mode, type 7 and the function 
header. The form for the function header should be determined by 
how the function is used. The six possible forms are shown in 
the following table. 


Number of Arguments [] H 2 


No Result nane name B А name B 


Result Zemame  Zename В 25А паке B 

The name of the function (represented by пале in the table 
above) can consist of any number of letters 4 to 2, underscored 
letters А to Z, digits 0 to 9, or the symbols _, А, or а, but 
must not begin with a digit, The function name must not be in 
use for another global function or global variable. In the 
table, Z is used as the result variable, А is the left argument, 
and В is the right argument. Апу other nanes could be used 
instead, provided they are used consistently in the body of the 
function. Names of system functions ох variables must not be 
used as the result variable or argument variables. 


After any of the forms in the table, there can be a 


semicolon and additional names separated by semicolons. The 
additional names declare variables and functiors to be local to 
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Summary of Function Definition. 


Creating a Function 
У2+А МАМЕ B 
Reopening Definition 
VNAME 
Display 
LU) (Display all.) 
(020) (Display from 20.) 
£200) (Display line 20.) 
Insert a line between [2) and [31 
[2.1] Pers 
Delete line [3] 
Саз] 
Replace line 13) 
(3) Peg+SxiN 


Line Editing for line (3) 


(3082 (Line 3, colum 8.) 
[3J P-<Q+sw 8 (The line is printed.) 
LL. + (Type / to remove, 1 to insert 1 space.) 
Сэ] Pe +5х1 N (Type additions in the spaces.) 


Extending line [51 
25002 


Context editing for line [2] 


[3) /.old phrase.new phrase (To replace.) 
[3] /.о1@ phrase. (To delete.) 
£3] /..new text (To extend.) 
[3] /.. (To display the linc and then 


extend it.) 


ии 


the function. (Local variables and functions are discussed later 
in this chapter.) 


The function header is line [0] cf the function. after 
entering a 9 and а header, function definition is said to be 
open. The system then types [1] on the next line to invite the 
user to enter line [:] of the function. The user can then type 
function lines, and the.systen continues to number lines. when 
the last line has been entered, function definition mode can be 
terminated by typing a v at the end of a line or on а line by 
itself. The v is recognized as long as it is the last nonblank 
character on the line, even if the line is a comment. 


Upon an attempt to close definition, the function header is 
checked for duplicate use of names, and statement labels are 
checked for duplication with names used in the header or names 
used for labels on other statements, In addition, tha form of 
the header is checked for correctness. Any of these errors 
causes the message ГЕРН ERROR and display of the header or the 
line with the incorrect label, The error should be corrected, 
then 7 should be typed to attempt to close definition again. 


REOPENING DEFINITION 


To add more lines to a function, first reopen definition by 
typing v and the name. No other header information should be 
used--use of other header information causes the system to assume 
you are mistakenly attempting to create a new function having the 
Same name as ап old function, (The header can be changed after 
definition is open by treating it as line [0) and revising it as 
described below.) ^ After definition of the function has been 
opened, the system types the number the next line will have. 
The user can type additional lines in the same manner as when the 
function was created. 


OVERRIDING THE LINE NUMBER 


After the system types a line number, the user can override 
that line number by providing a different one. For example, 
assume the system printed [4] because line [4j was expected. The 
user could type [2] to override the [4] if he wants to enter a 
new line (2). He could type the new line (2] on the same line he 
types the line number, or, he can type only the overriding line 
number and press RETURN, after which the system would type [2]. 
After line [2] is provided, the system would continue by 
numbering the next line with Га). 


To insert a new line between lines, use a fractional line 
number. Рог example, [3.2] could be used to insert a line 
between lines 3 and u. No more than в digits are allowed after 
the decimal point. The system continues to number subsequent 
lines by incrementing the last position of the overriding Line 


1-3 


number until another overriding line number is used. Thue, after 
[3.53] would follow (3.993, [5], [4.01], and so fo 


то remove a line, use a request of the form [a3]. The tilda 
before the overriding line number indicates that the line should 
peter voted. Nore than one line number can be provided (e:3., [43 
pe de]. Note that a line cannot be replaced by a blank line by 
overriding a line number with the number of tne line to be 
deleted and pressing RETURN. 


Line 70) (the header) сап be replaced like any other line, 
but it cannot be deleted. If the new line (2) causes the name of 
the function to change, the ola function remains as it was when 
function definition was opened, and a function having the new 
name is produced when definition is closed, The function name 
cannot be changed to the name of a global function or variable. 


when function definition is closed, all lines are renumbered 
with consecutive integers. Because line numbers can change, use 
af labels for all branching is recomended, 


If a #8 PULL error occurs during function definition, 
function definition mode is closed automatically, and all 
functions and variables remain as they were when function 
definition was opened. 


DISPLAY OP FUNCTIONS 


when function definition mode is open, the entire function 
can be displayed by typing 10). то display only line 3 of the 
fünction, type [30]. To display all lines from line [3] on. type 
PUS OEE you interrupt the display (sce Appendix C), function 
definition remains open unless a closing ? appeareó in the same 
line as the request for display. 


LINE EDITING 


Line editing can ba used to change individual characters in 
a line. To begin line editing, type something of the form (3087, 
эзге 3 is the number of the line to be revised, and 8 is the 
Approximate position in the line where the first change is to be 
appe The system thon prints the line and unlocks the keyboard 
below the eth character. Use spaces ог backspaces to position 
the typeball to the position to be changed. Type / under a 
character to delete it, or type а digit 1 to 9 to insert 1 to 9 
spaces before the character, or type А below it to insert $ 
spaces, а for 10 spaces, С for 15 spaces, and so on up to # for 
40 spaces. To replace a character, you must delete that 
character (which closes up the line leaving no new space) and 
type а i before the next character to provide space for the 
riplacement character, After the changes are specified and 


БЫ 


RETURN is pressed, the system prints the revised line and waits 
at the position of the first inserted space or at the end of the 
line if no spaces were inserted. Туре in any new characters in 
the spaces and then press RETURN. 


If line editing causes the line number to change, the old 
line remains intact, and anew line with the new number is 
inserted. To extend a line, use the form [300]. The zero as a 
position in the line causes the line to be printed зла the 
keyboard to unlock at the end of it. 


Note that line editing should not be uscd with a terminal 
that does not print the APL character set. Тһе APL system does 
not take account of single APL characters printing as more than 
one character on such terminals, so the position where changes 
are made can be somewhat unpredictable. 


CONTEXT EDITING 


Context editing allows replacenent of the first occurrence 
of a given phrase by another phrase. Context editing is often 
more convenient than line editing when the changes are localized 
in a small part of the line ard prior display of the line is not 
required. The line that is changed is the line the system is 
expecting next. The editing command has the forn 


/.old phrase.now phrase 


The / signals that what follows із an editing request. Тһе 
synbol immediately after the / is the symbol chosen by the user 
to mark the end of the first phrase and the beginning of the 
second phrase. Any symbol can be used as long as it occurs in 
neither phrase. The delimiter can optionally be used at the ела 
Of new phrase, but if it is not, the new phrase is assumed to end 
at the rightmost excursion of the type element (except that a V 
at the end is not considered part of the phrase). The system 
first searches for the old phrase, If the odd phrase is found, 
it is deleted and the new phrase is inserted at that point. If 
the old phrase is empty, the new phrase is inserted at the end 
of the line. After replacement, the system prints the corrected 
line. If both the old phrase and new phrase are empty, the 
system prints the line and unlocks the keyboard to allow the line 
to be extended, ТЕ the old phrase is not found, the error 


message 


13: PHRASE NOT FOUND 


is printed. (Note that the line number can be changed using 
context editing. When the line number is changed, the old line 
remains intact and the revised line is added tc the function.) 
If the editing request is incorrectly formed, РЕР Е: is 
printed. The following examples ustrate useful editing 
requests: 


P.QUR.SIX (FOUR is replaced by SIX) 


4.3.5,8.5 (A comma is used as the deliniter 
because periods occur in the phrase.) 
[3] 7.8. (Deletion of XiY+; [3] was used to 


override the line number that had 

been printed by the system.) 

(To extend the line with :0) 

(To extend the line with infdrmation from 
the keyboard.) 


FUNCTION DEFINITION SHORTCUTS 


In general, a line you type in function definition mode is 


used up before you are required to type another line, Рог 
example, you сап type [03]? to display line [3] and then close 
function definition. Or, you can type УР ЗАТ to орел 


definition, override the line number with [3], provide a new line 
(3], and close definition, А v at the end of a statement is 
always recognized, but other editing requests at the end are 
interpreted as being part of the line. tience VPN[3]Peiy[aD2V 
would cause line [3] to be P+ W[8ÜJ, It would not cause display 
of line [4] after replacing line [3). 


LINE SEPARATOR 


You can use the diamond symbol (the overstrike x for a 
Selectric terminal) as an input line separator for function 
definition mode. “he parts separated by diamonds are used as if 
they were entered consecutively fron the keyboard except that the 
normal line number prompt is suppressed. However, input li: 
for line editing requests must still be entered separately fri 
the keyboard. Апу diamonds preceded by an odd number of quot 
are considered to be part of character constants and not line 
Separators. ІЁ an error occurs, any remaining lines are 
discarded and input is again requested from the keyboard. ТА 
following example shows use of the line separator to define a 
function and then display it: 


SZeNEXTLINE N x L«CFREAD N w Ze(vAZe! ')/Z x TOV 
VZeNEXTLIUE 8 

[1]  Z«CPREAD N 

(21. getv\zet 10/2 
7 


The purpose of the line separator is to reduce waiting time when 
the computer responds slowly. The diamond is allowed as a line 
separator only in function definition mode and should not be 
confused with the use of the sane symbol in other versions of API 
to allow multiple executable APL statements on a line. 


LOCALIZATION OF VARIABLES AND FUNCTIONS 


The variables local to a function include all va 
appearing in the function header and all statement labels. 
Variables that are not local tc any function are called global 
variables. When execution of a function begins, the local 
variables take precedence over any other functions and variables 
having the same names. Other variables that were in effect 
before this function was called (that is, those not local to this 
function, which are called variables global to the function) 
remain accessible. When execution of the function is completed, 
the variables local to it vanish, thus releasing storage space 
for other uses, and any variables or functions global to the 
function become accessible again. 


As execution of the function begins, the argunent variables 
are assigned the values of the arguments in the expression 
invoking the function, If the function modifies the arguments, 
it is actually changing a copy of the original arguments. (See 
Chapter ll for storage implications.) The label variables are 
also assigned scalar integer values of the line numbers on which 
they appear. These variables are locked to prevent them from 
being assigned inappropriate values. (However, they can be given 
improper values if they are first erased and then given a value.) 
The result variable and any other variables listed after the 
first semicolon in the header have no initial value. 


A function can also have another function local to it if it 
has the second function's nane in its header. As for local 
variables, the local function is undefined as execution of the 
main function begins, The local function can then be defined by 
use of ПРХ or [COPY with СЕТУ having l as its value (the normal 
сазе --see Chapter 7 for details about DFX, (COPY, and ÜENV). 
When execution of the main function completes, the function 
local to it will vanish, just as a local variable would, and any 
temporarily inaccessible function or variable having the same 
name would again become accessible. 


FUNCTION EXECUTION » 

Function execution begins when the name of the function is 
encountered in an expression being executed and апу arguments 
have been evaluated. The system must save information about how 
far execution has progressed in the calling line in order to be 


able to eventually return to it and continue processing. The 
State indicator is a summary of this information and is available 
to the user. Execution of a function begins with establishment 
of local variables as discussed in the last section. Thea, 
except for branching, the statements are executed in order from 
first to last, After the last statement has been executed, the 


value last assigned to the result variable is returned to be used 
in the calling expression, and all local variables vanish. 
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Branching can be used to control which statement will be 
executed next. А branch statement consists of a branch arrow 
followed by an expression that returns a result. The value must 
be a scalar ог а vector, and unless it is an empty vector, the 
first value must be a nonnegative integer. If an empty vector is 
used, the next statement is performed, If the value is a scalar 
or vector, its first element is used as the number of the line to 
be executed next. If the value is 0 or exceeds the largest line 
number, the function exits. The following examples show useful 
branch statements. Close examination of the expressions to the 
right of the arrows should show how they generate appropriate 
line numbers: 


ELLIT <14 (Branch to line 5 if 4 is less than 14, Note 
that this will not work in 0-origin.) 


+(A=3)/8 (Branch if 4 equals 3 to line 8.) 


+001,22.13)02+х8] 
(Branch to 21 if В is negative, to 22 if 
zero, or to [3 if positive.) 


+(4›20 18 13 2)/£5,L4,L3,L2 
{Branch to ¿s if A is greater than 20, branch 
to Lu if greater than 18 but not 20, to line 
L3 if greater than 13 but not 18, to L2 if 
greater than 2 but not 13, or go to the next 
line if 4 is less than or equal to 2.) 


STATE INDICATOR 


Any lines that call for execution of another function cannot 
be completed until the other function has exited, Such 
unfinished lines are called pendent lines. If an error causes a 
halt at a line of a function, that halted line is said to be 
suspended, The state indicator is а record of all pendent and 
suspended lines of functions. It omits partially executed lines 
entered in immediate execution mode, lines entered for quad 
input, and lines used as arguments to the execute function. The 
state indicator with variables, displayed by the system comand 
)SIV, shows what lines are pendent or suspended ало also shows 
variables local to functions. An abbreviated form, displayed by 
the system command )SI, omits names of label variables and names 
appearing in the header after the first semicolon, For exarple: 


5ге 
[3]«ZePRINT 5;X;K:LINI 
[4] SIMU 4:13 


61:52 


251 
[3]*2-РАТЬТ 8 
[s] SIMU x 


In both examples above, the most recently invoked line is shown 
first. An asterisk marks a*line that is suspended, Hare, line 
[4] of SIMU called PRINT, and execution of PRINT halted at line 
[3] because of an error. Тһе )SIV display shows the foll 
function header followed by a colon and names of statement labels 
separated by colons. If the function has no statement labels, no 
colons appear. 


The )SIV display shows that the variable K currently 
accessible is the one local to PRINT. The other X local to SIMU 
is no longer accessible. However, the label variable £3 local 
to SIMU still has its value because no variable £3 is local to 
PRINT. In goncral, the current value associated with a variable 
name is that for its first occurrence on the state indicator. If 
it does not appear on the state indicator, the current value is 
that of any global variable having that name. 


A branch in immediate execution mode can be used to restart 
execution of the most recent suspended function. Вог example, 
+5 would cause execution of PAINT to continue at line 5. 
Usually, the function would be corrected or values of variables 
would be changed before proceeding. To remove the most recent 
suspension and the pendent lines that led to it, type a branch 
arrow with nothing to the right. А beginning user of APL often 
begins а new execution of а function without removing the old 
one, causing a large number of suspensions to accumulate. These 
unnecessary suspensions waste space and can lead to confusion by 
allowing local variables to make global variables inaccessible. 
When a suspension occurs, it is a good practice to either make 
corrections and continue execution or clear the state indicator 
by use of the niladic branch (see Chapter 2), An excessive 
number of suspensions can be eliminated by use of o ПЗАУЕ 'name" 
(see Chapter 7). 


тһе information the system keeps about pendent lines can 
become invalid if the pendent functions are altered, replaced, or 
erased. Тһе system responds by printing 14: SI DAMAGE апа 
surrounding with brackets the names of the affected functions on 
the state indicator display. Execution of the affected functions 
cannot be resumed, Experienced users are expected to avoid 51 
DAMAGE if they intend to continue execution of a halted function. 
Certain changes to suspended functions can also lead to SI DAMACE 
--specificaliy, altering the function header or changing the 
number or relative order of statement labels. 


HALTING A FUNCTION 


Wnile a function is running, it can be halted by an 
interrupt (see App. C). However, when the keyboard is unlocked, 


use of the interrupt on some terminals is interpreted as an 
attempt to revise the line being entered, То halt а function 
requesting quote-quad input, type the overstrike € (formed fror 
o, U, and T). This results in suspension as if an error had 
Occurred. To halt a function requesting quad input and remove it 
апа all related pendent lines from the state indicator, use а 
branch arrow with nothing to the right. 


TRACE AND STOP CONTROLS 


Any stop, trace, and timing controls in effect for a 
function аге cleared if function definition mode is used to 
change the function in any way. 


LOCKED FUNCTIONS 


A function can be locked by using # (V overstruck Бу ~) in 
place of 9 when opening or closing function definition. Locking 
a function prevents display of the function and prevents its 
definition from being reopened. An attempt to open definition of 
a locked function results in the error message DEFN ERROR. A 
locked function cannot be unlocked; if you will want to change a 
locked function at а later date, keep an unlocked copy of the 
function in another workspace protected hy a password or keep a 
printed listing of the function. If closing definition of the 
function results in SI DAMAGE, the request to lock the function 
is ignored. 


Chapter 2. Statement Form and Order of Evaluation 


This chapter discusses the form of legal APL statements and 
the order of evaluation of statements. Restricting the 
discussion to “APL statements" means that system commands (which 
are distinguished by beginning with a right parenthesis) are not 
of interest here, The meaning of a statement is determined in 
part by its form, but mainly by the functions used and the 
environment in which they are used. This chapter discusses the 
influence of form on meaning and leaves the functions and 
environment to be discussed in several other chapters. 


SPACES 


The use of spaces in an APL statement is usually unimportant 
to the meaning of the statement except for a few casas: 


{1) Names must be separated from other names by spaces, 
and names must be separated from digits of a number to 
the right by spaces. (Also, a name beginning with Е 
must be separated from digits to the left.) Otherwise, 
they would run together and appear to be all one name. 
Conversely, spaces in the middle of a name would make 
it appear to be two names. 


(2) Numbers next to one another must be separated by 
spaces, and spaces cannot appear within a number. 


(3) Spaces within a character constant are treated as 
any other character in the constant and affect the 
value of the constant. 


(4) Spaces in a comment (except for trailing spaces) 
are preserved by the system, Although they have no 
meaning to the APL system, they may be important to 
the reader of the comment. 


FUNCTION DEFINITION AND SYSTEM COMMANDS 


Аз execution begins for statements entered in immediate 
execution mode, entered in response to quad input, or used as 
arguments to the execute function (but excluding statements in 
the body of a function), a check is made to determine if the 
first nonblank character on the line is 9, 9, or ). Іп these 
cases the statement is preconverted to become a call to the 
function DPD (a program that performs function definition mode) 
or 057 (a program that performs system commands) with the 
original line as а character argument, Рог example,  vFNL6DJ 
Becomes DPD ‘9FW[60]’. То preserve the original meaning, any 
quotes in the original statement become double quotes after the 
conversion, Any comment at the end of the original statement 
Becomes part of the argument to DFD ог 057. The discussion that 
follows assumes that any such preconversion has already been 
performed. 


COMMENTS 


А comment may be entered in immediate execution mode or may 
appear in a function line. Comments begin with the symbol m and 
extend to the right to the last nonblank on the line. ‘The part 
of the line following the comment symbol is not executed. This 
allows the user to  intersperse descriptive text with APL 
statements. ‘The following example shows а comment used in 
immediate execution mode to add а description to the printed 
transcript of the session: 


Кер а TO GENERATE 2 ч 6, ETC. 


The following discussion makes no further mention of comments, 
although a comment may appear at the end of any line, or the 
comment may constitute the entire line. 


CONSTANTS 


Constants represent numbers or characters. For example, 
.14 5.23 is а numeric constant-vector, and "ABCD! is a 
Character constant-vector. Constants consisting of one character 
or number are scalars, while those having more components or no 
components are vectors. 


An unsigned-number is defined to be any of the following: 
digits 

digits.digits 

.digits 


where digits represents one or more of the digits 0123456789, 
The italic notation used here is used throughout this book to 


denote a term having a special definition. Here, digits 
represents a sequence of digits, not the letters d i g i г ands. 
Hence the following numbers are examples of unsigned-nurber 


3.8 
.05 
58 


However, ап unsigned-nunber cannot end with a decimal point. 
Керсе, would not be legal. 


А zumbar has any of the following form 


uasigned-number 
“unsigned-number 

unsigned-number exponent 
“unsigned number exponent 


The symbol ~ is used te express a negative number--the minus 
symbol cannot be used in its place, An exponent has one of the 
following forms: 


Edigits 
E'digits 


The # can be read “times 10 to the power," So, 1223 means 
1*10*23, and 3.2873 is the same ав ,0032, A numeric-cons i 
formed from one or more number, separated by spaces. 


A character-constant is of the form: 


'symbols* 
where symbols represents any number of APL symbols, including 
no symbols. The symbol ' in a character-constant is represented 
by two quotes. For example, 


ure 
IMS Y 


Quotes must always appear in pairs, An expression with an odd 
number of quotes results in a SYNTAX ERROR. 


The term constant mans either а  numeric-corstant ог а 
character-constant. 
FUNCTIONS 

Functions are of three kinds: 


(1) System functions, which have names that begin with J or 
Ш, are used to communicate with the APL system. 
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(2) User-defined functions, which have names formed in the 
same way as variable names, are the only ones the user can 
define. 


(3) Primitive functions (except those produced by operators] 
are symbolized by single characters such as +, x, +, etc. 


For the purposes of this chapter, the important features of 
functions are the number of arguments they require and whether 
they return results. Functions can be monadic (one argument), 
dyadic (two arguments), or niladic (no arguments). If rfunction 
is used to denote a function that returns a result and function 
is used to denote one that does not, the six possible forms are: 


dyadic-rfunction (руадіс, returns a result.) 
monadic-rfunctíon (Monadic, returns a result.) 
niladic-rfunction (Niladic, returns a result.) 
dyadic-function (Dyadic, no result.) " 
monadic-function (Monadic, no result.) 
niladic-function (Niladic, no result.) 


For sone primitive functions and system functions the same 
symbol or name is used for two distinct functions--one monadic 
and the other dyadic. The dyadic function is used if there is a 
left argument, and the monadic function is used if there is no 
left argument. 


Dyadic user-defined functions can be used without a left 
argument, but if the function requires a value for its left 
argument, а VALUE ERROR results. The following example is а 
function that can be used without a left argument provided its 
right argument is not negative: 


Vien Pi В 
[11 2+2хв 

[2] +(8zo)/0 
[33 2+2+4 V 


РІ 5 
10 

Pii 
05: VALUE ERROR 
Fila] 2-244 
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The function ONC, described in Chapter 7, can be used to check 
whether the left argument has Aa value. This could be used to 
write user-defined functions that have distinct monadic and 


dyadic forrs in analogy to distinct primitive functions having 
the same symbol. 


Whether а name refers to a function or a variable is a 
matter that can be decided only when the line begins to execute, 
Also, whether a function actually returns a result may depend on 
circumstances. For example, if a user-defined function was 
defined to return a result, but the result variable was not 
assigned a value prior to exit from the function, a VALVE ERSOR 
results 1f the expression calling the function requires а result. 


OPERATORS 


An operator is a special kind of function that takes 
functions as arguments and produces functions as results. 
Following are examples of four types: 


4t.*B (Inner Product.) 
A*.*B {Outer Product.) 
+/В (Reduction. ) 

B (Scan.) 


The operators are the period, /, and Y. In place of the : and = 
in the above examples, any dyadic scalar function symbols could 
be used. These operators are discussed in detai? in Chapter 6, 
but for the present, it is important to note that the forms 
exemplified by +.х and +,x represent dyadic functions that return 
results, and +/ and *\ represent monadic functions that return 
results. 


The axis operator is used to specify the coordinate along 
which an operation is to be performed. Only a few functions can 
be used with the axis operator and further details are discussed 
with those functions. Тһе operator is used in the form 
fusction-symbol[vaiue]. For example: 


$L 215 ` 
+/[1JB 


VARIABLES 

A variablo is a name that might be associated with a value. 
The vaziable-name is formed from any sequence of the letters 4 to 
Z, underscored letters А to 2, digits 0 to 9, or the symbols ^, 
а, or  , but the name cannot begin with а digit. System 
Variables are special variables with names that begin with D or 
П. The rest of the nane can be composed in the same way as normal 
Variable names. Only the system variables recognized by the 
system can be used--the user cannot invent new ones. 


An indexed-variable is of the form: 


variable[ list) 


A variable-name having no value associated with it can be used 
only immediately to the left of an assignment arrow; otherwise a 
VALUE ERROR will result. 


VALUES 


A value is any of the following: 


variable 

constant 
indexed-variabla 
monadic-rfunction value 
left-argoment dyadic-rfunction value 
níiladic-rfunction 
left-argument 
variable-name*tvalue 
indexed-variable+value 
(value) 

Tvalue 


The last case has the further restriction that the + may appear 
only as the first character of a line. 


Use of an indexed-variable to the left of a specification 
arrow sets the values of elements of the variable without 
changing tke shape of the variable. Used elsewhere, the index | 
returns parts of a value. 


I 
| 


The assignment arrow can be used to give a value to a 
variable or to change the value of a variable. The result of the t 
Zssignment (not to be confused with the value of the variable) is 
the value used on the right. Consequently,  4-2[1 21+3 is the 
same as the two statements 2[1 2]+3 and 4+3. Similarly, A-DeB is 
che sane ав Пев and 4-8; but A+B is aot the same as +2 and, 


А-П. ' 


The operations to find a value occur in right to left order, 
Hence, 3x2+uü means 3x(2+u), When а dyadic function is! 
encountered, the right argument is preserved while the expression 
producing the left argument is evaluated. Hence, 


А-3 
(А-ч)хА 
12 


However, it is poor programming practice to take advantage of the: 
right argument being preserved; some APL systems produce а 
different result in cases like the one above. Моге generally, 
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any value encountered in the right to left scan is preserved. 
For exanple, 


Arh $ 6 
ALA 2 1]-4 
A 

654 


{On some APL systems the result would be ч 5 4 or 6 $ 6 because 
the variable on the right is not preserved, while on other 
systems such operations are prohibited.) However, the following 
example shows a case where the value is not preserved because the 
scan has not reached the variable: 


А+2 
А+А+<3 


LEFT ARGUMENTS 
A left-argument is any of the following: 


variable 
constant 

constant( list] 
indexed-variabie 
fvalue) 

(уа1ие) [113] 
niladic-rfunction 


For example, 3 сап be used as a left argument, ALPHA can be used 
as a left argument, and '123'[2) can be used as a left argument, 
but 2x3 cannot unless it is enclosed in parentheses. In fact, 
in 2035, the 3 would actually be used as the left argument to 
EXPRESSIONS 

An expression is the same as a value except that it need 
not return a result that can be used for subsequent operations. 
An expression is any of the following: 


monadic-function value 
left-argument dyadic-function value 
niladic-function 

value 


The last case, called niladic branch, can be used only as the 
leftmost character of а line, “he branch with no value or 
expression to the right causes exit from the executing function 
and fron all other functions on the state indicator up to any 
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previous suspension. 
LISTS 
A lise is of the form: 
list-element 


list-elament;list-eloneat 
list-element;list-element;list element ... 


The list, if used for an index, must have one list element for 
each dimension of the array being indexed. 


A list-elemeot can be: 

vacant 

value 

expression 
An expression that does not give a result can be used in a list 
used for indexing and is treated as if the list element were 
vacant. A list element is vacant if there is nothing at all in 
that position. For example, P(3;J illustrates a list having а 
vacant list-element. 


The elements of a list are evaluated in right to left order. 
Hence 


А-3 ; 465 
gives A а final value of 3. Note that the semicolon is not an 
APL function. Lists can only be used for indexing and output. 
Expressions like the following are illegal: 
99 (A528) 
Also, the statenent 
ЗрА:В 
is equivalent to 
434); 
not 
30(AiB) 


The expressions separated by semciolons are evaluated separately, 
then their results constitute the list. 


LINES AND IMPLICIT OUTPUT 
А line is any of the following: 


value 
expression 
list 
vacant 


When a Jine is a list, the list elements are printed in left to 
right order. “he list can contain a mixture of character and 
numeric values as shown belcw: 


1-30 
'TUE VALUE OF X 
TEE VALUE ОР X IS: 34 


Scalar and vector list elements are printed on the same line (if 
ПРУ has not been exceeded), but printing of a matrix or array of 
higher rank begins on a new line, and any subsequent vector or 
scalar begins on a new line. ^ List elements that are vacant or 
that produce no results are skipped over. 


1f the first list element is а niladic branch, no output is 
produced. If the first list element is a branch with a value to 
the right, the value of the branch is printed along with the 
other list elements, then the branch is taken. 


When the line is а value, the value is printed unless a 
specification or branch occured as the last operation. Hence, 
3+2 would print a result, but 4-3+2 or oven (4+3+2) would not. 


STATEMENTS 


А statement is either a iine or a line with a label. The 
label із а variable-name and colon placed before the line. For 
example: 


ax =Y 


ВЕРЕЯ 


А label on а statenent entered in immediate execution mode, for 
quad input, or in the argument to the execute functicn is 
ignored. 


QUAD AND QUOTR-QUAD 


The system variables (| and T are used for input and output. 
When they are assigned a value, the system prints the value. 
when their values are usod in an expression, the system reads 
input from the keyboard to provide the value. 


when M input is requested, the keyboard unlocks (normally 


with the type element at the left margin). Any characters typed 
аке returned as a vector, except that a single character gives a 
scalar. 


When 0 input is requested, the system prints D: and then on 
the next line indents six spaces and unlocks the keyboard. Any 
APL expression that returns a result сап be entered, If the 
expression is incorrect or does not produce a result, an error 
message is printed and the input request is repeated. For 
example, 


AO 
0: 
в (This is the input line.) 
05: VALUE ERROR 
B 
n 
n: (The input request is repeated.) 
2x1 
4 
2468 


А branch in quad input does not actually effect a branch. 


The D can be used for output to conserve lines in a program. 
The statement 0-4+8 has the same effect as the two statements A+B 
and D-3. 


тһе M суррої, when used for output, is slightly different 
from П used for output. Ordinarily, APL output is followed by a 
carriage return so that the next input or output will begin on a 
new line. However, when quotc-quad is used for output, the extra 
carriage return is suppressed. This allows the program to 
continue output on the same line or to give output and then 
request input on the same line. For example, 


VZeASX B 
[13 0+2 
[2] 2+0 v 


P+ASK "AGE? ' 
AGE? 38 
P 
38 (Note leading blanxs in the result.) 


The leading blanks show where the typeball was positioned when 
the keyboard was unlocked. The person who was typing could have 
backspaced and replaced the blanks with other characters. Алу 
leading blanks can be removed by using (vABs! ')/B«D. Note that 
ОРЫ is not ignored when M output is used. If the number of 
printed characters reaches ПРИ, the system inserts a carriage 
return in the output and indents 6 spaces hefore continuing the 
output. 


Chapter 3. Scalar Functions 


The class of scalar functions includes those functions that 
can be defined for scalar arguments and then can be extended to 
other argunents through elemert-by-element extension, That is, 
if the function is monadic, the result has the same dimensions as 
the argument, and the elements of the reault are found by 
applying the function to all elements of the argument. For the 
dyadic functions the following rules apply: 


1. If the arguments have the same shape, tho result has 
that shape and is formed by applying the function to 
the corresponding elements of the arguments. 


2, If one argument is a one-olement array and the other 
ig not, the result has the shape of the one that is not 
one element. Тһе one-element argument is used with 
each elenent of the other argument to form the result. 


3. If both arguments are one-element arrays 
has the larger of the ranks of the arguments. 


the result 


For the dyadic functions, the arguments must either have 
identical shapes ог at least one must be a onc-element array. 
Any other arguments produce a RANK ERROR if their ranks diffe: 
or a LENGTH ERROR if their ranks match but dimensions diffe: 
The following examples illustrate some of these rules: 


Teát 3p19 
3 


x: 2 
k 5 5 
? 89 
4 (A monadic scalar function.) 
x Дык D 
та 78 76 
7» 78 79 


DARE 


Nie acepte 


Summary of Scalar Functions. 


Dyadic Function Monadic Function 


A+B 
Addition 


1-Е 4 minus 8. 
Subtraction] 3-%+* 1 


Sum of д and 8. +5 Same as 6*5. 


3450 


Same as 0-8. 
aditive 


АТВ 
Maximum 


Inverse 

base Product of 4 х5 Sion of B.Same 

Times and B. Signum Јаз (820)-8<6 
2247-8 x3 0 “2071 0 71 

A+B д divided by 8, +2 Same as 148. 

Divide Division by 0 is not || Recip- ftot allowed if В 


allowed except that 
020 is defined to 


| rocai lis 0. +.2++5 
be 1. 332e€*1.5 | 


Larger of A and _ ТВ If B is an 
B. af Se+5 7217571 | Ceiling integer, the 
result is 


that integer. 
Otnerwise the 
smallest integer 
greeter than 5. 
[2.5 39 3 


ТЕ B is an 
integer, the 
result is 

that integer. 
otherwiss the larg- 
lest integer les: 
than в. 
12.5 3++2 3 


Smaller of 4 and 
B. 315+>3 
1075.975 


д to the B 
power. А may 

be zero if 2 

is not negative. 
deo is defined to be 
1. I£ 450, Ë must 
be representable as 
a rational fraction 
with an оба 
denominator. 


+B 
xponent- 
ial 


2.718281828...) 


Logarithn 


Base 4 logar- 
ithn of B. à 
must be positive and 
must not be l, 


Summary of Scalar Functions, Continued. 


T. 


solute Value of 


ale The remainder of 8 
Residue divided by 4. Magnitude |3. 13 о 73«:3 03 
More precisely, 
R-ARLBSATA=O 
ЛІВ Humber of combi- 15 Factorial of В 
Combinations nations of В Factorial |for nonnegative 
of things taken 4 integers. Otherwise 
at a time for -he mathematical 
positive integer сатта function of 
arguments. More 3+1. Not defined 
generally al# for negative 
_| OB) (14) %15-А integers. Д 
дов The argument А 78 random choice 
Circular determines which Roll from үн. Depends on 


function from the 
following table 
is applied to 8. 
А must be an 
integer in the 
range 77 to ? 


0 (1-8*2)*,5 
1 sin B 
2 cos B 
3 tan B 
à (18B& 205.5 
5 sinh B 
5 cosh в 
2 сапа В 


Equal 

Not equal 

Less than 
Greater than 

Not greater than 
Not less than 


arc sin B 
arc cos 3 
arc tan B 
(71+8*2)«.5 
arc sinh 5 
arc cosh B 
arc tanh В 


Result 1 if the 
relation holds, 0 
otherwise. 


325 6 3 20 0 1 1 


4. 


AAB AND Elements of А B AAS AvB ААВ AYB 

ANB OR А and B dod 9-1 1 o ° 

ANB HAND must be 1'а ото 1 1 ° 

Ava NOR ог 0's. 10 0 1 1 ° 
АВА АВ ос о o 1 1 
дув++-ДУВ 


244 (Scalar argument and matrix argument. 
2 а 6 
8 10 12 
є 16 18 


Ata (Two arguments with identical shapes.) 
чо 
10 12 
14 16 18 


p(1 1ə4)+(1 1 1р3) (The larger rank prevails.) 
So. 2 


The table at the beginniug of this chapter describes most of 
the functions in complete detail. Most of these functions are 
fariliar mathematical functions or incorporate very sinple 
concepts. Therefore, the discussion below deals with only a few 
of the less familiar functions or special cases. 


FLOOR AND CEILING 


The functions floor and ceiling always return an exact 
integer. The result depends on the value of (СТ as follows: If 
(18-NINT B)sQCT«(ie |NINT B) the result is WINT 9, where NINT B is 
the nearest integer to B. Otherwise, the result is the least 
integer larger than g for ceiling, or the largest integer smaller 
than B for floor. поќе that B-L can be negative in cases where 
Сот is not zero ала B is slightly less than an integer. 


POWER 


15 keeping with proper mathematics, the power function does 
not allow taking square roots of negative numbers (e.g., ~1*.5), 
but it does allow taking cube roots of negative numbers (e.g., 
7i*:3). To distinguish these cases, the power function attempts 
to represent the right argument P as a rational number fim, where 
5 is an integer and M is the least integer such that (Уе |Р. 
Note that (W:M)-|P depends on (C7. If the left argument із 
negative and the rational representation has an even denominator, 
the power function gives а DOMAT ERROR. If the left argument is 
negative and the rational fraction has an ода denoni»ator, the 
result is negative if the numerator is odd and is positive if the 
nunerator is even. 


The residue function is slightly more sopisticated than the 
definition in the table, For example, 212-.5*ÜcT would give the 
improper negative result -.5«[CT. Тһе actual algorithm returns 
zero if S-AxLBiAtA=0 would give a result having a sign opposite 
to the sign of 4. 


3-8 


COXBINATIONS-OF 


The combinations-of function returns limit values of 4:3 if 
A, 8, Or 3-4 are negative integers. “hat is, the result is zero 
if А, B, and B-A are all negative integers or if В is not а 
negative integer but either 4 or 8-4 is a negative integer. 


CIRCULAR FUNCTIONS 


The domains and ranges of the circular functions are given 
below. 


я мов Domain Range (-#)08 Domain Range 


(1-2*2)*.5 1218 122 

sin B 1212 | arc sin Р 1218 (0.5)2]Z 
cos в 2212 | arc cos В iz|D — (220)^2s01 
tan P arc tan B Со, 5)212 
{1=8*2)*.5 ast | Cieme2)5,5 1518 02 

sinh В ‘| are sinh 8 

cosh B 152 | arc cosh В 153 052 

tanh 5 1212} arc tanh B 1215 


RELATIONAL PUNCTIONS 


The functions = anëz are the only scalar functions that can 
be used with arguments of character type. Characters can be 
compared with numbers, but the result always shows inequality. 
Por numeric 4 апа 3, the result for А-В is 1 if 18-А is not 
greater than [efx|s. The three conditions АВ, 4-8, and 4^? are 
always exclusive. For example, if 4-3 gives 1, then 4>8 and 4«B 
give 0. The range where two numbers are considered equal is 
illustrated below: 


ASB A=B А>8 
— + 


B-lerx|B в B+DUCTx |B 


Note that when В is zero, А=В gives 1 only if A is exactly zero. 


Chapter 4. Array Concepts and Indexing 


Ап APL array can be visualized as an arrangement of values 
along n orthogonal coordinates, where n is 0 to 75 for this 


particular APL system. The positions along the coordinates are 
numbered 1, 2, 3, etc. in l-origin, and they are numbered D, 1, 
2, etc. in 0-огідіп. Тһе number of elements along a coordinate 


can be 0 or more. Тһе lengths of the array along the coordinates 
are called the dimensions of the array, and the number of 
coordinates is called the rank of the array. The nares scalar, 
vector, and matrix are used to denote arrays of rank 0, 1, and 2, 
respectively. No special names exist for arrays of rank greater 
than 2. The APLUM system has an arbitrary limit of 75 as the 
maximum rank of an array, but in practice, this limit is so 
large that it is not restrictive. Contrary to common casual 
practice in mathematics, an APL array has а definite rank--a 
Ons-element vector is not the same as a scalar, and a matrix with 
one row or column is nct a vector. 


The last coordinate of an array is conventionally considered 
to be the column coordinate, the secord from last coordinate is 
the row coordinate, and the third from last coordinate is the 
Plane coordinate. The following examples show hcw various arrays 
can be formed and displayed: 


(A scalar.) 


4 (A vector.) 


2 3pr6 (A matrix.) 
3 
6 


2 32 ABCDE*' (A matrix of characters.) 


^ 


Summary of Chapter 4. 


Function 


Description 


Vo8 
Reshape 


Returns a vector containing the 
dimensions of 3. The result 
has 0 elements for a scalar 5, 
1 element for a vector, and 2 
elements for a matrix. 


Torms a reauit having the dimensions 
specified by the left argument and 
having elements taken from -he 
right argument in odometer order. 


The result is a vector containing 
all elements of B in odometer 
order, 


Indexed 
selection 


The result has as dimensions 
(211), (I2), (013), ... COTR) 
and contains those elenents of 
B for which their first 

index is in I1 and their 

second index is in I2, etc. 

If a list element is vecant, all 
possible index values are used. 


RUI1:I2:19; 
ee 31-8 
Indexed 


The indicated elements of # 
are set to corresponding values 
from B. Either B must 


specification|be a one-element array, or the 


dimensions of 2 must match 

(pI1), (012), (213), + (pie) 
except that dimensions of 1 are 
ignored. If a list element is 
vacant, all possible index values 
are used. 


2 з 40128 
таза 
5678 
3 10 21 12 
13 14 15 15 
17 18 19 20 
21 22 23 28 


(Two planes, three rows, four columns.) 


The last example shows that а rank-3 array is printed as a number 
Of matrices separated by 1 blank line, A rank-4 array would be 
printed as a number of ranx-3 arrays separated by two blank 
lines, and in general, a rank-¥ array is displayed as a ruber of 
arrays of rank №-1 separated by #-2 blank lines. Ап empty array 
prints as a blank line. 


One often visualizes an array as a spatial arrangement of 
values. The spatial conceptualization leads to use of zerms like 
"shape of array" and "vector along the Xth coordinate." These 
terms are important enough to give precise meanings fcr them. We 
define the "shape of an array" to be the result given by the size 
function (to be discussed in this chapter). Аз a consequence, а 
Vector and а one-row matrix have different shapes, even though 
they may be visualized to look the same (and in fact, the system 
prints them identically). We define "a vector along the Kth 
Coordinate" to ba a vector of those elements in the array for 
which the coordinates other than the Ath are the sare, and the 
Ith element of the vector has J as its th coordinate in the 
array--that is, a line of values aligned in the direction of tho 
Xth coordinate. 


RESHAPE: HeVpH 


The reshape function was used in some of the previous 
examples to form arrays. ‘The function forms a result having the 
dimensions specified by the vector (or scalar) left argument and 
having elements taken from the right argument. Elements are 
taken in firat to last order, and if they are exhausted, they are 
used again beginning with the first. — The right argument must 
not be empty unless the result will be empty--"reshape never 
makes something out of nothing." 


ORDERING OP ELEMENTS 


The elements of an array are considered to be ordered. “ne 
reshape function takes elements according to this ordering. ‘The 
ordering із the same as the order in which the elements are 


printed by a terminal. Тһе order is called odometer order 
because the indices (coordinate positions) vary in the same way 
as the digits of an odometer. For example, for an array 43 


having dimensions 2 3 4 the elements in odometer order are: 


A3[1;1;1] 


43023934) 


SIZE: RepB 


The size function returns a vector of the dimensions of its 
right argument. Because there is one element in the result For 
Gach dimension of B, the result has 0 elements for a scalar P, 1 
element for a vector, 2 elements for a matrix, and so forth. 
Коке that because ов has one element for each dimension of 3, 
pna gives the rank of В as а one-element vector. The following 
examples. illustrate the size function for arrays of various 
ranks: 


23 {A scalar.) 
(A blank line indicates an empty vector 
result.) 
ops I 
° 
ШЕ {А vector.) 
3 
49 
1 
p2 3pi6 (А matrix) 
22 
pp? 3р6 
2 
p2 3 5p130 (A zank-3 array.) 
225 


pp 2 3 5р132 


RAVEL: 26,8 


The ravel function returns а vector result containing all 
the elements of the right argument in odometer order. For 
example: 


„2 3016 (Changing a matrix to a vector.) 
1223556 


9.3 (Changing a scalar to a vector.) 
1 


The ravel function can be useé to Getermine the number of 
elements in an arbitrary array. The number of elements in 3 is 
2.8. (Note that the ravel function could be omitted in this 
expression if ¥ were always a vector.) 


INDEXED SELECTION: #+8[11;12;13; ... 


Indexed selection chooses those elements of ап array for 


which all indexes occur in the respective list element For 
example, if M is a matrix, (3:41 gives the element having 3 as 
its row index and ч as its column index. Similarly, М2 3:4 5] 


gives those elements in the second and third rows that are also 
in the fourth and fifth columns. If a list element is vacant, 
iW is used, where 7 is the length along that coordinate. The 
index values nust 5e integers in the range of coordinates of 
elements in 3. The index list for an array of rank X must have 
K-1  semicolons. The result Я has the dimensions 
(o11),(p12), (013), ... (oth). Hence the rank of R is the sum 
of thà ranks of the indices. If the incices are vectors, the 
result satisfies 


R[K1:K2;K3; ... IKS)SBLIIUR1):I2C42]:23[33]; s.e SINCKNJA 
When the indices are not all vectors, the result is: 
(Сала), (рг), Сда), se- #1810) рас, газ, X23. I3; ... $1 


Indexed selection cannot be applied to а scalar. The following 
examples show indexed selection applied to vectors ard matrices: 


yes 6 3 12 

vti) 
E 

vos) 
12 

vost (An error results from a request 
07: INDEX ERROR — for ал element that does not exist.) 
vos] 
Й 

YL5:6: [Because V is a vector, its rank is 
CG: RANK ERROR incompatible with the index list.) 
Vt5:67 


+ 


vin 2 131 21 


363238 
0-3 49112 
123% 
5 627 8 
9 10 11 12 
C232) 
7 
#2; 1 (Row 2, all columns.) 
$678 
ME:31 (All rows, column 3.) 
3711 
M2;3 ај 
?8 
MUT 2 1;3 13 
зла 
78 
зл 


U«Xe3 502 з 2 3 +22 53213121 
345 


нью 


31 
* .lex'tx 


(A matrix of characters.) 


INDEXED SPECIFICATION: R[I1;:12;I3; ... :183-В 


Indexed specification allows setting of selected elements of 
8. The index list indicates elements to be set in the same way 
аз for indexed selection (see previous section). The 
restrictions on list elements are also the same as for indexed 
selection. The array 2 must be a scalar (or one~elenent array) 
or must have dimensions (211), (212).(023), ... „(р1#) except that 
dimensions of length l are ignored іп the comparison, If B is 
not a scalar (or one-element array), the elements of B are taken 
in odometer order and placed in appropriate locations in R, If 
two elements of 8 are placed in the same position in #, the last 
one in odometer order in B prevails. Both R and B must be of the 
Same type (i.e., character or numeric). “he shape of Я is not 
changed by the operation. Я must not be a scalar. 


уез 6 3 
vt2lei 


10 


12 


2 31-10 12 
12 

УГЗ $J-35 1% 
v 

16 


DeM-2 зо’ =? 


ИС151 2 31='o' 
и 


С :11+'0' 
M 


МС1:2 3]e' ex 
и 


(А scalar is used 


repeatedly.) 


(All rows, column 1.) 


У 
е 


Chapter 5. Mixed Functions 


The class of mixed functions includes all functions that are 
jot system functions, composite functions, or scalar functions. 
lecause few patterns exist between the mixed functions, they most 
е discussed individually to describe the arguments they allow 
nd the results they produce. Chapter 4 already discussed the 
hree mixed functions reshape, size, and ravol, 


XCEPTION RULES 


Most of the mixed functions have "normal" cases for which 
he results are relatively simple to express in terms of the 
‘дите They also generally have additional special cases 
ас are convenient but are treated as exceptions, The following 
ге some of the reasons these exceptions are allowed: 


Exceptions to overcome notational difficulty. There is 
no way to represent an empty numeric vector constant in 
an expression, and 10 is inconvenient to use as a left 
argunent because it must be surrounded by parentheses. 
Hence ''p# is allowed in place of (10)p8. However, 
the only other case where ar empty character argument 
is allowed where a nonempty character argument would 
not be is the catenate function, (However, the system 
functions (115702, ОТЕАСЕ, and DLTIME also allow empty 
character left arguments.) Another class of exceptions 
to overcome notational difficulty arises because it is 
not possible to type a one-element vector constant. 
Because a constart consisting of a single character or 
number is а scalar, many functions allow a scalar in 
place of а one-element vector. However, the left 
argument for index-of and the arguments to grade up and 
grade down are not allowed to be scalars. 


Summary of Mixed Functions Presented in Chapter 5. 


Function Description, Examples 


`B Produces a vector of the first 
Index B integers. 15—+1 2945 
generator 
— 
vB For each element of 2 gives 
Index-of the first index in the vector 


У where the element is found 
or 196и (in l-origin) if the 
element is absent from Y. 
567 816 5 222 15 


AB Returns 1 for each element of 
Merbership 4 that occurs in B and returns 
0 for other elements of 4. 
13562 3++0 1 0 


51752 1 Chooses 51 random numbers from 
Deal 182 without any duplications. 


The Ith element of the vector 
Grade up result is the index in V of 

the Ith smallest value in V. 

VLAV) gives Y sorted in increasing 
order. 63.3 5.2 1.123 1 2 


w The Ith element of the vector 
Grade down result is the index in Y of 
the Ith largest value in У. 
VLTVJ gives 7 sorted in decreasing 
order. 


А,ЕК1В Joins 4 and В along the Ath 

Join coordinate. 1 2 3,4 5+» 
12345 

V/CKIE T== Tesult includes elements 

Compress along the Kth coordinate of В for 


which there are corresponding 1'5 
in 7 and does not include elements 
for which there are 0's in Y. 
101/12 3++1 3 1 0 1/'48С' +3 ' АС” 


Summary of хей Punci 


ns Presented in Chapter 5, 


Continued. 

Function Description, Examples 
VERIS r Expands by inserting zeros (if в 
апа is numeric) or blanks (if 8 is of 


character type) where there are 0's 
in y and selects consecutive 
elements along the ith coordinate 
of В where there are l's in V, 
101 0\3 в-+3 ои 0 

20 rVàBtesd BU | 


"m | Selects the first (if AL41:0) or 
Take last (if A[K]«0) ТАК) elements 
along the xth coordinate of B, 

If |4[K] exceeds (р8)ГЕ], 

zeros or blanks are used as the 
extra elements. 3*1 2 3 4 5+1 2 3 
COR'ABCDOE'e»'CDE! 4+1 2++1 200 


A+B Drops the first (if A[K]>0) or 
Dr last (if A[X)«0) [A(X] elements 
along the Xth coordinate of B. 
1f |4(KJ exceeds (p8)[K], 

the xth dimension of the result 
is zero. 3+1 2 3 ú Seen 5 
З+'АВСОЕ" e ABI 
———FÓ,AnC——n-n—[ ss .-_ . — | 


EKIB Reverses the order of elements 
Reverse along the xth coordinate of 8. 
$5 6 7447 65 Q'ABCD'*+'DCBA' 
ALXOB. Shifts vectors along the kth 
Rotate coordinate of B ín a negativo 


direction (for 4»0) or positive 
direction (for A«0). 

2012 3 4 535 512 

29 'АВСОЕ'++' DEABC" 


2 
Y 
f 


[7 Reverses coordinates of E. 
Honadic mx 
transpose 


ANB Interchanges coordinates of 5 
Dyadic according to 

transpose The Kth coordinate of the result 
corresponds to the (А=К)/‹рА 
coordinate of в. 


— 


Sumnary of 


ixed Functions Presented in Chapter 5, Continued. 


Function Description, Examples 
А\В Evaluates В аз a number 
Base represented in a number system 
value having radices 4. 


22 211 0 1e5 10 10 2012 3 4-723 


ATB Represents 8 in the number system 
Represent having radices 4. 

2 2 275++1 0 1 10 10 101296-*42 9 6 
ав Executes the character vector В 
Execute as an APL statement. 

a iste 2 3 6 5 
"в Produces а character array гергеѕоп- 
Monadic tation of B. Except for treatment 
format of lines longer than OPW, 


"В looks exactly like P when printed. 


Dyadic 
format 


Ba 
Matrix 
inverse 


ABB 
Matrix 
divide 


Represents columns of 8 

according to the format specified 
by pairs of numbers on А. The 
first element of a pair in А is 

the width of the field (0 to have 
the system choose a width), and the 
second element of the pair gives the 
number of digits beyond the decimal 
if positive, If the second element 
of the pair is negative, its absolute 
value determines the total number of 
digits, and exponential format is 
used. 


Matrix inverse of B. Sane as 
THB where I is an identity 
matrix. 


Solution to a system of equations 
{for a square matrix 8) or least 
squares regression coefficients 
(if B has more rows than columns). 
Same as (В2)+.х4. 


Exceptions to ignore dimensions of 1. at times it is 
Convenient to treat а row or column of an array as а 
vector, while at other times it is more convenient to 
treat it as a matrix. Consequently, some flexibility 
has been built into functions to allow extra or missing 
dimensions of 1. 


Generalized scalar extension. The dyadic scalar 
functions allow a scalar argument to be used repeatedly 
with all elements of the other argument. More 
generally, some mixed functions allow a single vector, 
plane, etc. to be used repeatedly with parts of the 
other argument. 


ARRAY TYPES 


An array, even if it is empty, is either of character type 
or numeric type. Those mixed functions that rearrange elements 
of an array or select elements gf an array always return a result 
having the same type as the right argument. For example, 
0p'ABCD' gives an empty result of character type. 


AXIS OPFRATORS 


For several of the mixed functions (and composite functions) 
an axis operator can be used to specify the coordinate along 
which the operation is to be performed, If no axis is specified, 
the last coordinate is assumed. Alternate symbols can be used to 


perform the operations along the first coordinate. These forms 
are: 
Last coordinate First coordinate Kth coordinate 
3.8 AB A. EXTR 
А/В AtB АКВ 
ANB ANB А3029 
$8 өй ФСЈ 
Афв дев P 


Note chat the symbols for performing the operations along the 
first coordinate are not allowed to be used with an axis 
operator. For example, e[(X18 would produce a SYNTAX SaROR. 


The value used for an axis operator must be a onc-element 
array, and for functions other than join, it must Le an integer 
in .pp8 (except that if B is а scalar, it may be “irti). For 
the join function (e.g., A.[K)8) the value of X may be an integer 
in (os4)[(ppB)fi or a half integer obtained by adding or 
subtracting .5 from one of those integers. 


INDEX GENERATOR: Я+1В 

The index generator function produces a vector of length RB 
containing the first 3 integers. Тһе result depends on the 
current origin. 


В must be а one-elemert array containing а 


Requirements for B. 
nanmegacive integer. 


Examples. 
13 (In l-origin.] 


Dro«o 
15 
61234 (In 0-origin.) 


10 
(Blank line indicates (0 is empty.) 


INDEX-OP: R-/iB 


The index-of function returns for each element of р the 
least index I in the vector 7 for which УСТ] equals the element 
of B. If no value in V is equal, the result element is 1+ру in 
l-origin, or pV in 0-осідіп. The comparisons use GC? so that 
elements of V and B may be considered equal even if they differ 
slightly. 


Requirements for V and B. V must be a vector--a scalar is not 
Dr] а 


пау be of any shape and the result will have that 
shape. 
Examples. 
4 5 612 5 
à 2 
D-M-2 3р 'DEFGRI' 
D8? 
GHI 
"HIDE 00G' AM. 
заз {А matrix result for a matrix right argument.) 
8:2 
7 в 91'42' 
uuu (Characters never equal numbers.) 


^ ABA tA 'ABAB' 


1212 
070+2 
"ABA 'ABAE' 

0163 (The G-origin result is 1 less.) 


MEMBERSHIP: Rede’ 


The membership function returns 1 for each element of д that 
occurs in В. For numeric arguments the comparisons use the 
current value of DC7, so values may differ slightly and still be 
considered equal. 


Requirenents for 4 and 2. 4 and 8 may have any shape. The 
Teule has tha Бале shape аз д. 


Examples. 
123632649 P 
101 
'ABCD' e BACKS * 
12110 
Urae2 30 'carpoc? 
сат 
DOG 
Ак'бдАТ' 
011i 


0 11 (The result has the shape of the left argument.) 


!G0AT' cA 
1111 


"ABC EL 23% 
оо? 
DEAL: 51252 


The deal function chooses at random 51 values from 152 
without repetitions. 


Requirements for 51 and 52. Both 51 and 52 must be onc-element 
arrays containing nonnegative integers such that 51552. The 
result is a vector of length 51. 


525 
12534 


070+0 
575 
32012  (0-origin.) 


GRADE UP AND GRADE DOWN: Rega and 3-08 

The 7th element of the vector result x is the index in Ë 
where the Ith smallest (for grade up) or the Ith largest (for 
grade down) element of В occurs. The comparisons do not use DOT. 
If а value occurs more than once in 8, the indices of those 
values occur together in R in increasing order, 


Requirements for В. P must be a nuneric vector. The result # is 
а numeric vector of the same length as B. 


Exanples. 


43.8 2.1 2.2 4.4 1.1 5.5 
25321485 


$3.9 1.1 2.2 5.8 1.1 5.5 
6u1325 


Ve3.3 1.1 2.2 4.4 1,1 8.8 
УГУ} (To sort in increasing order.) 
1.1 1.1 2.2 3.3 а.ч 5.5 


7117] (To sort in decreasing order.) 
5.8 4.4 3.3 2.2 1.1 


Peo eS 12 
('ABCDS'£PI)L4P) (4P is the inverse of a permutation 
ABCDE vector P.) 


X-'ABC' 
Y='pzF* 
Ze'GHIt 
(XY MA4 0 2 1 12 0 02 1) 
AGDEUBCIF (Select next from x for a D, ¥ for a !, 
2 for a 2.) 


JOIN: Rea, (LIB 


The join function connects 4 and А along a coordinate 
already existing in A or B or along a new coordinate of length 1 
inserted into each. “he first elements along the coordinate come 
from A and the rest come from P. When K is an integer, the 
Operation is called catenate. When K is not an integer, the 
operation is call laminate and the new coordinate of length 1 
is inserted into each argument between the existing LX coordinate 
and ГК coordinate. 


Requirements for 4 and №. Except for the special cases below, 
A and $ must have the same rank, and dimensions other than the 
Kth must be the same; that is, (K#ipsA)/cd and (X#1pp8)/p8 must 
be the sare. The types of A and B must be the same unless one or 
both are empty arrays. (Warning: some APL systems do not allow 
empty arrays to have a different type. It is recommended that 
differing types be avoided for compatibility.) The shape of the 
result is the same as the shaze of the two arguments except that 
the Kth coordinate of the result is (pA)(X]+(p2)EK). I£ both 
argunents are empty and of differing types, the result is 
nuneric. 


Exception cases. If 4 ог 8 is а scalar (but not both), it is 
reshaped to have the shape of the other argument except that the 
kth dimension is l for catenate. If both argusents are scalars, 
they are treated as one-element vectors for catenate. For 
catenate, one argument may have a rank l less than the rank of 
the other argument. In this case a new coordinate of length 1 is 
iaserted to become the «th. 


anp} 


123,456 (Joining two vectors.) 
456 


0+2 3otet 


O+¥+3 Sptot 


MEAN 


ooo 
ооо 
ооо 
00-2 so'0' 
0000 
оосо 
HAL 
***0000 
* #0000 
и E 
m 
m (The scalar is treated as a one-colunn 
matrix.) 
LAETI {A vector is treated as a one-colunn 
weed matrix.) 
m" 
H.bi1'345' (А vector is treated as à ono-row matrix.) 
m 
345 
32 3,[.5Ju 56 (Laminate along а new first coordinate.) 
123 
456 
123,[1.5)ч 5 6 (Laminate along а new last coordinate.) 
14 
25 
36 
1 2 3,[1.5)8 
14 
24 
34 


COMPRESS: R-V/LK]B 


The compress function shortens В along the Xth coordinate by 
omitting those elements for which there are corresponding 0's in 
v. 


Requirements for у and p. V must be a vector and all elements of 
V must be l's or 0's. The length of V must be the sane as 
(pB)(X]. The result has the same dimensions as Р except that the 
xth dimension is «/v. 


-10 


Exception cases. If v or P is a scalar it is treated as a 
Оро elenent vector. “hen if у is а one-slerent voctor, it is 
extended to the length of В along the «th coordinate. IÉ В is 4 
one~element vector, it is extended to the length of y. 


Examples. 
10103312345 
135 
1 0 1 0 1/'4BCDE' 
ACE 
17 'АВСРЕ 
ABODE 
of 'ABCDE' 
(Blank line indicates an empty result.) 
Temes 40112 ^ 
1238 
5 6 7 8 
9 10 11 12 
1011/4 
138 
B. 8 
$1112 
1001/0209 (Same as 1 0 E 
1 2 аза 
8 0 11 12 
t o 4⁄4 
въ 


EXPAND: Я+У\ЕХ18 


The result is formed by expanding 5 along the kth coordinate 
by filling with zeros (if p is numeric) or blanks (if ic of 
character type) in those positions in Р for which there are 
Corresponding 0's in V. 


Requirements for v and в. Ignoring the special cases, V must be 
a vector Containing only 2's and O's auch that C470) s CoB)EK]. 
The result Я has the same dimensions as 8 except that tho AiR 
dimension is oy. 


Exception cases. If Yor ais a scalar, it is treated as a 
Sne-élement vector. 


5-11 


131024223 
12263 
DeMe2 39:6 
122 
45 
19 t01W 
19203 
s0506 
10 241)4 (Same es 10 14и.) 
123 
000 
s 56 
51/2 
1 (A vector result.) 
тоу" (An empty array can be expanded.) 
з 
oio 
D 


ТАКЕ: peyta 


The take function selects  |V[X) first elements (for Y[K1>0) 
or last elements (for y[4]«0) along che th coordinate of 2. If 
ТСК] exceeds (pz)[&], zeros (if p is numeric) or blanks (if в is 
of character type) are used to provide the extra elements. 


Requirenents for y and p.  Tgnoring the special cases below, у 
adt Ба а Vector having an integer for each dimension of B. That 
is, (оу)=ров. The result я has dinensions |У. 


Special cases. If y io a scalar, it is treated as a one-element 
Speciali 


Vector. if p із а scalar, it is treated as а one-element array 
of rank p7. 


Exanples. 


at 'АВСОЕ" 


“54M (First 2 rows, last 5 columns.) 


er 


3410 (Take can be applied to an empty array.) 


2315 (S is treated as a 1 by 1 matrix.) 
в < 


DROP: 2<V+B 


The drop function forms its result by omitting |V(K] first 
elements (if VCX]»C) or last elements (if V[K]«0) along the Xth 
coordinate of B. 


Requirements for ¥ and B. Ignoring the special cases below, V 
пай De А Vector os integers, and pV must be tho same as ррй. 
The result has dinensions of(¢3)-|¥, 


Special casos. If V is a scalar, it is treated as a one-element 


vector. 1f 8 is a scalar, it is treated as a one-elerent array 
of rank ру. 


Exanples . 


3412394 5 . 
ч5 
72s! ABCDEF * 
ABCD 
20012 8 
{Blank line indicates an empty result.) 
Den<3 oi12 
i 3$ в 
5 & 7 8 
3 10 11 12 


1 72 4M(First row and last 2 columns are cropped, } 


5 6 

9 iC 
20 0.3 

11 (The scalar was treated as a matrix.) 
(10743 

3 


REVERSE: Р+Ф[К)В 


The reverse function reverses the order of elements along 
the xth coordinate of 3. The result has exactly the same shape 
as s. 


Exanples. 
$3456 
6523 
M'ABCDEE* 
РЕРСВА 
Dees 40112 
1238 
5 5 7 6 
9 10 11 12 
ot 
wo 38: 92 & 
8765 
12 1110 3 
eH (Sane as o[12M.) 
3 10 11 12 
567 8 
3 2 3 + 


ROTATE: Л+АФ[КОР 


тһе rotate function shifts elements of 3 along the Kth 
coordinate a number of positions specified by 4. For positive 
elements of 2, the elements move so that their indices decrease, 
and for negative elements of 4 their indices increase, Elements 
shifted beyond the end are replaced at the other end. The 
absolute value of the elements in A gives the number of positions 
the corresponding vector along the Xth coordinate of 8 is 
shifted. 


Requirements for 4 and S. Ignoring the exception below, 4 mest 
have one element for each vector in 3 along the ¿th coordinate. 
That is, pA must be (K#1995)/c8. Thus the mensions of 4 mist 
be like those of B except that the Xth dimension of # is abseni 
from A. The result has the same shape as 2. 


Special cases. If А is a scalar, it is extended to һесопе an 
Da aving dimensions suitable for.H. ^ Rotation cf a scalar is 
allowed, but the left argument must be a scalar, and the result 
is the same as 8. 


Examples. 


2 $ 41 23 4 $ {Rotation by 2 positions to the left.) 
345512 


2 q : 2 34 5(Rotacion by 2 positions to the right.) 
45123 


2 @'ABCoE' 
CDEAR 


0-5-3 4p112 
2 3 4 
„ЕС. 
01112 

о 1298 
& (Rows are shifted.) 
7 
10 


71 1 2 eB (Sane as 3 7i 1 2 9[1J8.) 


. 102 

239 44 

6 7 85 > 

10 11 12 9 (All rows are shifted by 1.) 


MOUADIC TRANSPOSE: К+9Р 


The monadic transpose function reverses the coordinates in 
B. Thus the last coordinate in R corresponds to the first in P, 
the second to the last corresponds to the second in 3, and so 
forth. Рог a vector or scalar, the result is the зале as the 
argument. Рог a matrix, the result is the usual matrix 
transpose. For an array of rank 3, AlTiv;Z] is the sane as 
В0;732], The shape of the result is фра. 


Examples. 
Ü-Me3 üpi12 


5 234 
5678 
9 io 31 12 
aw 
153 
2 616 
з 711 
s 8 12 
D+C+3 up'FOURFIVEFORT" 
POUR 
FIVE 
FORT 
ac 
РРР 
ого 
ove 
REP 
Пе}#3+2 3 49124 
1234 
5 6 7 8 
9 10 11 12 


13 24 15 16 
17 18 19 20 
21 22 25 25 


12 2% 


DYADIC TRANSPOSE: 8+УаВ 


The dyadic transpose function interchanges coordinates of 5 
according to the integer values in the vector V. 


Requirements for у and 8. Ignoring the special case below, V 
must be а vector having one element for each dimension of S--that 
is, V and В must satisfy (рУ) =роВ. ‘The elements must be integers 
such that (1[/V)ey and Ve://V (all integers wp to the largest 
elenent in У but no other values). Тһе rank of Я is [/V in 
l-origin or i+f/v in O-oricin. Тһе Ith dimension of ° is 
LZ ('2I)/708. The Ith coordinate of 3 becomes the V{I]th 
coordinate of А. If two or more coordinates of 8 map into the 
same coordinate of R, the length along that coordinate is the 
least of the related dimensions in В. 


Special case. If V is a scalar, it Ís treated as a one-elemert 
vector. 


Examples. ^ 


0+3 up'ABCDEFGHIJKL" 
Aged 
ERGH 
IJXL 


21am 
AEI 
ЗРЯ 
сб GE Z3eBU ;I3.) 
DHL 


1 iu (НЕГ]=ВГТ:Т1. The diagonal of the matrix. 
АРК Note that the length is the shorter 
of the two dimensions of the matrix.) 


D<A3=2 3 ¥p124 


1 2 3 4 
5 6 ? 8 
9 10 11 12 


5 6 7 8 Ее НК 
17 i8 19 20 


9 10 11 12 

21 22 23 24 
1 1 1843 

1 18 (RUII-BUI:I;I]. The main diagonal. ) 
1 2 1843 

1 5 9 

19 18 22 (RLI;J)sBLIi/i;I]. A diagonal slice.) 
2 1 2843 (RÜI;JIS8UZ;2:7].) 

а. їй» 

5 18 

9 22 


The expressions to the right which relate elerents of В, У, and 
R are formed as follows: The indices applied to f аге 
iT/V)g IJXL...', and the indices applied to н are МКБ... 1(У7. 


BASE VALUE: ДІВ 


The base value function evaluates its right argument as а 
representation of a number in a general number system described 
by its left argument. For example, 2 2 211 0 1 gives 5; the 
vector 1 0 1 is evaluated as a number represented in Базе 2. The 
left argument, 2 2 2, contains the radices of the number system, 
(Radices are ratios between the weightings of the positions.) 
For the simple case of a vector left argument д, the th 
weighting (in 0-origin) is x/(-K)+4. That is, the xth weighting 
is the product of the last K elements of А. If W is a vector of 
these weightings, the result for А18 is ¥+.»2. Thus for the case 
2 2 211 0 1 the result is +/4 2 1*2 0 1. 


Requirements for 4 and B. Except for the special cases below, 4 
and п must satisfy Citoa)-itee (the last dimension of 4 must be 
the same as the first dimension of 8). For arrays А and В, the 
vectors along the last coordinate of 4 are used to find vectors 
of weightings, and each vector along the first coordinate of P is 
evaluated according to each vector of weightings. The weightings 
are Wed\(pA)t@4,1. The result is then W».xB ‘he result has as 
dimensions (71+рА).1+рВ (same as the dimensions of А+.хВ). 


Special cases. Ifa or В is а scalar, it is treated as а 
one-element vector. If the last dimensicn of 4 does not match 
the first dimension of B but one of the two dimensions is 1, that 
dimension is extended to match the other. 


5-18 


Examples. 
24 50 62112 3 
3723 (One hour, two minutes, and 
3 seconds is 3723 seconds.) 


6 60 6011 2 3 (The first element in the 


3123 left argument has no effect.) 
Седе2 322 2 2 10 16 10 
222 
10 10 10 
U-B-3 01 13231401053 
1132 
0140 
1053 
ALB {Each vector along the first coordinate of 8 


S 6 25 11 is evaluated according to each vector 
101 110 345 203 along the last coordinate of A.) 


515 4 S (Evaluates the polynomial (3x.5a2)+ 
7.75 (ux,5)#8, The left argument is extended 
ta become a 3-element vector.) 


REPRESENT; П+АТВ 


The represent function represents its right argument in the 
number system described by its left argument. For example, 2 2 
275 gives 1 0 1. The left argument contains the radices of the 
number system. For a vector left argument and a scalar right 
argument, the result is given by the following function: 


ЯЯ+А SREP BiH 

[1] aoe 

[2] Я+йро 

[3] 11:+(#=2)/0 
[sl aCe leas] В 
C5) 3+B-RIR] 

ге] *(8=0)/0 

[7] в+взА[#] 

тв] N<8-1 

19] +6: v 


This function is а generalization of the usual method of 
converting between number systems by dividing and finding 
remainders. 


Requirements for д and в. А and B wey have any shape. Each 
glement of в is represented according to the radices in each 
Sector along the first coordinate of 4. (If 4 is а scalar, it 
vector ted as а one-element vector for this operation.) The 
aS ensions of the result are (p4),08 (i.c., the same as for outer 
product). 


Exa ples. 
10 10 107273 
28 
24 60 6073723 (3723 seconds is l hour, 
123 2 minutes, and 3 seconds.) 
22 2731 (High-order information is lost.) 
X11 
а 2 2131 (High-order information is 
711 intercepted by using a zero.) 
10 10 10734 281 
° 2 
з 8 
4 1 
Qraes 2p0 10 2 10 2 10 
о :0 
210 
2 10 
Ar281 323 
70 80 
23 
° 1 
8 2 
з. 
1 з 


EXECUTP: R++B 


Che execute function performs АРІ, statements in the vector 
or scalar Р. A result is returned only if the expression 
produces a result. When the execute function is performed as the 
Каре operation on a line, any result is automatically printed 
jase gPSpecification ог a branch was the last operation within 
the argument. Branching in the argument has no effect, an? апу 
Uhstement label is ignored. If execute is applied to a character 


argument representing a list, the list is printed аг 
list element is returned as the result of the execute 
Hote that the present system does not allow expressions 
150 characters to be executed. (Some staterents of as 
characters give a LIMIT 2RROR.) 


the first 


Examples. 


#71 2& &B' (Converting characters to numbers.) 
1 28 48 


e323 
лах. 
20 
Реза! 
Р 
123 
Peat2; 354" ы 
234 
P 
2 


MONADIC FORMAT: Rev? 


The monadic format function returns a character array that 
when printed looks exactly like Б (except possibly when ОРУ is 
exceeded, in which case numbers in v3 could be split between 
lines). | An argument of character type 18 returned unchanged. 
For a numeric argument, each colunn of 8 becomes several columns 
in the result (depending on DPP and the numbers in the column), 
but the other dimensions of the result are the same as for the 
argument. ‘Thus the rank of Я is the same as the rank of 8, and 
»R matches oE except that 1107 {the last dimension of Р) is 
generally greater than “itp2 (the last dimension of 4). Note 
that the exact output format differs between APL systems and may 
even differ between versions of the same system. Programs should 
be written to be independent of such differences. 


Special case. A scalar numeric argument is treated as a 
one-element vector and thus produces a vector result, 


Examples. 


25 
123 


01123 


$3 39112 


1 2 9 4 
5. 38, 3 8 
3 10 11 12 

pY3 &рї12 
3 i10 

vias! 
AB 


DYADIC FORMAT: 2+V¥B 


mhe dyadic format function represents columns of B according 
to pairs of integers in the vector V. The first number of a pair 
in V gives the width, and the second number gives the precision 
to be used in representing the number. The width is the nunber 
Gf character positions to be used for the column, and if 0 is 
Used, the system chooses a width so that at least one blank will 
Separate that column from the preceding column. The result R has 
Re same dimensions аз B except that the last dinension of R is 
usually greater than the last dimension of в. Character 
arguments аге not allowed. ‘The precision has the following 
significance: 


precisionz0 The numbers are xepresented in decimal format, 
The precision is the number of digits beyond 
the decimal point. If the precision is sero, 
no decimal point appears. 


precision<¢ The numbers are represented exponential format. 
The number of digits shown is the absolute 
value of the precision, and if the precision is 
l. no decimal point appears. Five columns are 
required for the exponent, unless the system 
chooses the width, in which case the number of 
Columns required for the exponent depends on 
the magnitude of the numbers. 


Note that a domain error vill result if а number cannot be 
represented іп the space provided. However, “there is no 
requirement that spaces separate numbers in the same row. 


Exception cases. If B is 'ascalar, it is treated as a 
one-elenent vector. (Hence the result is a vector, never а 
Sealar.) If V is а scalar or one-element vector, it is extended 
fo become V~0,/. (Thus the width of the columns will be chosen 


Бу the system.) “hen if ру is 2 but “its (the last dimension of 
В) is not 1, V is replicated to become V+(2x 1+рЁ)рУ so that the 
pair of numbers in V will be applied to all columns. 


7 3%.3456 2.8 326 
в 2.890928. 006 


47,3456 2.6 928 
0.9456 2.8000 928.0002 


1 0v2 3p1 0 
101 
010 
101 


10 73*3 102.9557 5.23518 75.35 5 
2.3550 
4.23510 
75.302 6 


717155 1.286 1.852 
185 156 262 


MATRIX INVERSE: Р+ЁВ 


The matrix inverse function returns the inverse of a matrix 
B. The inverse is such that 


(BB) т. ве» 


where Г is an identity matrix (i.e., а matrix with l's along the 
diagonal and D's elsewhere) having 1*»3 rows and columns. Hote 
that this uniquely defines Я only as long as 3 has the sane 
number of rows and columns, However, if B has more rows than 
columns, the result A can be uniquely defined Бу 
Reo(B(Q3)+.*B)+.x08, The result is related to the result for the 
ауабіс matrix divide function according to 88-768, where I is an 
identity matrix having “itp rows and columns. 


Requirements for #. Ignoring the exceptions below, B must be а 
matrix such that (1*pB)2 1*52 (B must have at least as many rows 
as columns) and 5 must have an inverse, lote that some matrices 
do not have inverses and produce а DOMAIN ERROS if an inverse is 
requested. In particular, a square matrix with two identical 
rods or with one row that can be produced by multiplying other 
rows by factors and adding them has nó inverse. Actually, there 
fs no precise distinction between matrices that have inverses and 
those that do not, and ОСТ is used in the test. Increasing the 
value of ПОСТ may prevent a DOMAIN ERROR, bst the result зо 
produced is less reliable and may be completely meaningless. “he 
dimensions of the result are $o2 (i,e., 298). 


Special cases. If P is а scalar, the result is the scalar +2, 
If В is а vector, the result із 5%+/5*2. Except for the result 
rank, the scalar case is the same as if the scalar were treated 
as a one-by-one matrix, and the vector case is the same as would 
be produced by treating the vector as a one-column matrix. 


Examples. See the examples at the end of the following 
discussion of matrix divide. 


MATRIX DIVIDE: — &«4BB 


The matrix divide function solves systems of simultaneous 
equations or finds least-squares regression coefficients. When 
the matrix В has the sane number of rows and columns, R is the 
solution to linear equations represented by the constant vector 
4 and the coefficient matrix 5. When 2 has логе rows ог columns, 
the result ? contains the regression coefficients for a dependent 
variable А and independent variables in the columns of В. Note 
that the result is the same as (E5)*.*4. 


Requirements for д and 4. ignoring the special cases below, в 
mus е а matrix such that (1t902)2 1*53, and B must have an 
inverse (sea the preceeding discussion of the matrix inverse 
function). Also, А must be a matrix such that (1+р4)г1+рВ (they 
must have the same number of rows). When А has more than one 
Column, the result # has a solution column for each column of A, 
The result has the dimensions (1%28),11рА (one row for each 
column of В and опе column for each column of 4). ‘The result Л 
satisfies B«.*Re-A if B is a square matrix. When Z is not a 
square matrix, the result minimizes each clement of 


+/(A-B+.xR)*2 


That is, В+.х# gives predicted values for the regression 
cofficients R, and 4-2*.x7 gives the residuals; so the sum of the 
squared residuals is minimized. 


Special cases. The arguments may also be scalars ог matrices. A 
scalar is treated as а one-by-one matrix, and a vector is treated 
аз a one-column matrix, After this extension, 1tpA must match 
1tpB. The dinensions of the result are (1408),:104 where À and 
B here are the original arguments before extension. 


Example 1. To solve the system of equations: 


S= x + 2y 
4=5x + 3y 


Use 


5 4 ma 
1 3 (A vector result.) 
(2 105 4) By 
^ 
3 (A matrix result.) 


The answer is x: 


1, y=3. 


Example 2. Given У1+.8 .9 1,0 2.2 2.1, Veet 2 3 1 2, and Yeu.5 
2 0.3 7.1 find the values of Ai and 42 that most nearly 
Satisfy Y-(41«V1)-42*V2 in the least squares sense, 


OPP+3 
1424788 
1.37 2.56 


The predicted values for г are: 


Qt xz 
3.66 5.35 9.04 5.56 9.37 


and the residuals are: 


Y-Q+.xZ 
0.895 0.252 3.159 2.72 72.27 


Example 3. Using Vi and V2 from Example 2 and ¥2~5.5 9,6 11.2 
10.3 3.1, find 41, 42, and Аз that most nearly satisfy 
Y2:A4+(á2xV1)+43xV2., This problem is like the previous one 
except that we imagine 41 to be the coefficient of a vector of 
l's. The solution is given by: 


D-B-1.Q 
.8 
.9 


nuwune 


E 

E 
Y2gB 

5.76 0.593 1.25 


Chapter 6. Composite Functions 


As described in Chapter 2, an operator is a special function 
that takes functions as arguments and produces a function as a 
result. Except for the result of the axis operator, these 
resulting functions are the composite functions. A few examples 
will help to illustrate this. The expression +/12 3 ("the plus 
reduction of 1 2 3") is the same as 1+2+3. Similarly, -/1 2 5 is 
1-2-3 or 2 (remember that it is performed from right to left). 
The function symbol to the left of the siash indicates the 
particular dyadic scalar function to be used. The forms for 
Composite functions are d/8 (reduction), а\в (scan), дз.ав (outer 
product), and 44.08 (inner product), where d and D represent 
symbols for any dyadic scalar functions. 


REDUCTION: Я-9/[Х]8 


Reduction applies a dyadic scalar function repeatedly 
between elements in vectors along the Zth coordinate of B. For a 
vector В, the reduction is of the form 


BL 1)é3t 21a ABEN] 


For higher order arrays the same sort of operation is performed 
for each vector along the Kth coordinate, Wher the axis oporator 
is omitted the operation is performed along the last coordinate, 
The alternate symbol / can be used to indicate the operation 
should be performed along the first coordinate. 


Requirements fox B. Elements of g must be in the domain of the 
Scalar function used. Thus, charactcr arguments are allowed only 
for the functions = and «. Except for the special cases below, 
the result has a rank that is one less than the rank of в and the 
dimensions of the result are (X«izpB)/c8 (the same as the 
dimensions of 8 except that the kth dimension of P is missing). 


Special cases. A scalar is treated as if it were a one-element 
Vector, and the result is then a scalar. If the length of a 
along the th coordinate is l, the result is the same аз the 
argument except that one dimension is removed. Но operation is 
actually performed in this case, so no check is made to see 
whether the values are in the domain of the function, except that 
arguments of character type are still illegal for functions other 
than = and =. When B is empty but the result is not empty, the 
result contains the identity element for the function if 


£” one 
exists. The following table shows the identity elements used. 
Note that in some cases the identity elements are identities in a 
rather loose sense. Some are right identities only, some are 
left identíties only, some are both, and some are identities only 
for logical arguments. Functions for which there is no identity 
in the table produce DOMAIY errors when applied along а 
coordinate of length 0. 


Function Identity Function Identaty 
* ° * 1 
- o ^ 1 
x 1 Y с 
n 1 i 1 
Г 74.268322 > с 
L > 1 
= 1.265322 H ° 
* ° s 1 
Examples. 

F731 9 15 

15 (Largest element.) 
1/3 1915 

Н (Smallest element.) 
x/1 2345 : 

120 (Product.) 
+/1 2345 

4% (Sum.) 
-/1 2 3 & 5 (Alternating sum; same as 

E 1+{+2)+3+(-)+5,) 
3/1 2 з ^ 5 (Alternating product; seme 

1.875 as (1xa%5)#204.) 
[eP-3 вра12 

1238 

5 8 7 в 

S 10 11 12 


E] 
`> 


P (Largest element in each row.) 


s 8 12 
Гар (Largest element іп each column.) 

9 10 11 12 
+з {A scalar is treated as a vector.) 
м5 

5 (No domain check ror one element.) 
4/10 

o (An identity if the length is zero.) 
*/3 0р0 

000 (An identity for each of the 3 rows.) 
мїлєВ (Gives 1 if all elements of the vector 4 


occur in 8.) 


V/AeB (Gives 1 if any elements of the vector 
A occur in B.) 


SCAN: R+d\l KJ8 


Scan performs a series of reductions. For example, «M 2 3 
4 5 returns 1 3 6 10 15; that is, the Ith element is 4/118. For 
arrays other than vectors, the result has the same shape as the 
argument, and the elements along the xth coordinate are produced 
by performing a reduction over the first 7 elements. Arguments 
of character type are not allowed. if the axis operator is 
absent, the last coordinate is assumed. The alternate symbol x 
can be used to indieáte the operation is the be performed along 
the first coordinate. 


vyoo10010 
920111111 


^11010 
119000 


к\з 23456 
1 2 6 24 120 720 


Ds2+3 39112 


1238 
5 8 7 в 
$ 10 11 12 


+P 
1 3 610 
5 11 18 25 
9 19 30 42 


+АР (Same аз ›\Г11Р.) 
123 wu 
6 8 10 12 
15 18 21 2% 


OUTER PRODUCT: A+ Ae. dB 


Outer product applies а scalar dyadic function using all 
elements of A as left arguments and all elements of 8 as right 
arguments. The rank of the result is (орА)+ррВ and the 
dimensions of the result are (pA4),pB. Each result element has as 
its first ppA indices the indices of the element used from 4 and 
has as its last pp8 indices the indices of the element used from 
B. 


Exanples. 
12 3%. 5 6 7 
"5$ 6 7 
8 10 12 44 (Each element of the left argument is 
12 15 18 21 multiplied by each element of the right.) 
12 13 


ное 
oor 
Boo 


+/1 2 39.-3 13 
102 (The number of l's, 2's and 3's 
in the right argument.) 


INNER PRODUCT: “R+Ad.DB 


Inner product applies the scalar function D between each 
vector along the last coordinate of 4 and each vector along the 
first coordinate of 3, then performs a reduction using d to that 
result, The usual matrix product is 4+.х8. 


Requirements for 4 and В. Ignoring the special cases below, the 
Jest dimension of Я must match the first dimension of 8. The 
dimensions of the result are (“1+pA),1+02 (all dimensions of А 
except the last and all dimensions of P except the first). 


Special cases. If Aor Б isa scalar it is treated as a 
one-element vector. Then if the last dimension of 4 does not 
match the first dimension of Р but one of the two dimensions is 
1, that dimension is extended to match the other (thus allowing 
the array having the 1 as a dimension to be used repeatedly). 


Examples. The following table shows examples for arguments of 
various ranks. 


p рой goR 
2 2 2 
2 1 1 
1 2 Е 


The following examples illustrate useful inner products: 


04:2 3p1 0, 


101 
6:0 
04843 3919 
123 
556 
789 
дав {Matrix Product.) 
3 10 12 
4 5 6 
1gpop'+.="X2CD' (Counts matches in corresponding 
2 positions.) 
D«TABLEe3 Wg'FOURFIVESIX ' 
POUR 
PIVE 
SIX 


PABLEA.='PIVE* 
(Gives 1 for a row that matches 
ЗЕТИЕ.) 


Chapter 7, System Functions and Variables 


This chapter discusses system functions and variables other 
than [ and 7 (which were discussed in Chapter 2), other than the 
ones related to shared variables (which have not been implemented 
in the present version of APLUM), and other than DPD and 537. 
System functions and variables allow communication with the APL 
system, and, to some extent, with the KRONOS operating system 
under the control of which the APL system runs. In most respects 
system functions and variables behave as other APL functions and 
variables except that: their names are distinguished by beginning 
with the symbol Ü or f, they control the APL environment in ways 
that other functions and variables cannot, and the values of 
system variables can change between settings. For example, 21, 
which is a vector of accounting information, may be set by the 
user to any desired value, but tke next tire he requests its 
value, it will correctly reflect ^ current ^ accounting 
information--that is, the system resets the value of DAI before 
it is read. Similarly, DAI can be erased by the user, but the 
system gives it a value whenever its value is requested. 


The system variables that affect operatio of the APL system 
have restricted shapes and domains. For example, 070, the origin 
for indexing, nust have a value of, l or 2, Any attempt co set 
DIO to an improper value will result in a MANK ERROR ог а DONATI 
ERROR, However, the user can erase ПІС or declare CIO to be 
local to a function and then fail to assign it a value. When a 
system variable is undefined and its value is required for an 
operation, an IMPLICIT ERROR results. For example: 


т2+10Тл B;DIO (010 is a local variable.) 
[1] Zea 9 


ICTA 3 

01: IMPLICIT ERROR 
I0TAUL] Zei2 
Й 


Summary of Chapter 7, 


Output Control 


OPP+integer (1 to 15) 
Printing precision--maximum number of significant digits 
Used for numeric output. 


ZPWeintéger (39 to ~1+2*17) 
Maximum printing width used for output. 


ZPL*pagesize,linecount (0 to “1+2*17) 
Print lines. Print lines to be used before a halt to ellow 
the terminal operator to intervene, and count of lines used. 
If 02201] is 0, output will be uninterrupted. 


Indicators affecting Primitive Functions 


OcT+number (0 to .01) 
Comparison tolerance used for relational functions, 
Membership, index-of, and domain tests. 


010+0 or 1 
Index origin. Determines base for counting. 


URL-integer (1 to 71*2«87) 
Random link used by random number functions. 


Function Definition 

СИТО ох 1 
Environment control, Affects OCR, ОРХ, ISX, OPC, OIL, 
ÚSTOP, üTRACE, DLOCX, GLrrus, DNAKSS, and Qcory. I£ OSAV 
is 0, the global environment is used, and if ОРНУ is 1, 
the current environment is used. 


macrixeJCR 'name! 
Canonical representation of a function in the form of в 
matrix. 


8-ОРХ matrix 
Fixes the function represented by the character matrix 
Argunent. The result returned із а vector containing the 
nane of the function, or, if the operation failed, a numeric 
scalar line number for the erroneous statement. 


уессог-ЈЕХ 'names" 
Expunges (erases) objects naned by the right argument. The 
result contains 1's for names that are now available, 0's 
for others. 


vector-iWC 'namos" 
Returns the name class for each name--0 for available, 1 
for locked variable {label or group), 2 for unlocked 
variable, 3 for function, or 4 for distinguished name. 


matrix-QNL 7 

matrixe'letters’ UNL V 
The namelist functions return matrices of names in use. 
Which names are returned depends on class numbers in 
V--locked variables (labels or groups) if 1,0, unlocked 
variables if 2eV, functions if зу, and defined 
distinguished nanes if wey. The loft argument of the dyadic 
form should contain letters to further restrict names to 
those beginning with those letters. 


vector*ÜLOCK 'names" 
Locks functions and variables named by the right argurent. 
The result is a vector containing l's for success, 0's for 
failure. 


Stop, Trace, and Timing Control 


У USTOP 'пале' 
Sets stop controls for lines specified by V and clears 
controls for other lines. 


2-05ТОР ‘папе’ 
Returns а vector of line numbers for which stop controls are 
selected. 


У OPRACS ‘папе’ 
Sets trace controls for lines specified by V and clears 
controls for other lines. 


Z+OTRACE "папе! 
Returns a vector of line numbers for which trace controls 
are set. 


V DLTIPE ‘name’ 
Selects accumulation of line timing information for lines 
specified by V and clears time accumulation for other lines. 
Also clears tire totals to 0. 


ZeDLTIHE ‘nase’ 
Returns a matrix with line numbers in column 1 and times (in 
millisecouds) in column 2. 


Program Library Functions 


OWSID+' name! 
QWSID contains the workspace identification of the active 
workspace. This name ‘Is used when no nane is given Zor 

ОЗАУЕ. 


TeSAVE ' мзлапо С: passwd] {/options =! 
Saves а ccpy of the active workspace ander tho name 
specified. [S4Vz'' (no nare given) uses the name in OWSID. 


à DSAVE 'wsnamo i:passwd)[/oprions]" 
Same as above except that 4 controls the state indicator of 
the active and stored workspaces. If А is 0 ог 1 the state 
indicator is cleared or backed up to the last suspension, 
respectively. 


OL4*' expression’ 
he latent expression is executed immediately after the 
workspace cohtaining it is loaded, 


(L040 '[*saccounc] wsname [:passwd]' 
Activates а copy of a stored workspace and thon exccutes the 
latent expression if one is defined. 


matrixrY (NAMES '[*account] wsnane L:passwd]" 
Lists names used in a stored workspace. The result is a 
matrix of names of objects in the name classes specified by 
elements of y--locked variables (labels ox groups) if 167, 
unlocked variables if 2cY, functions if 31, ani 
distinguished names if bev. 


maztrixeÜNAMES '[+saccount] vsname [:passwd]! 
Returns a matrix of ali names of classes 1, 2, and 3 in the 
workspace. 


matrixe'names! [COPY '[«account? wsname [:passwd]" š 
Copies specified objects into the active workspace from a 
stored workspace. 


matrixeDCOPY 'Cwaccount] wsname [:passwdl" 
Copies all objects of classes 1, 2, and 3 from the 
workspace. 


UDROP '[*account] wsname [:posswal! 
Removes the stored workspace or file named by the right 
argument from the indicated library. 


2-061В 'lsaccount] (аата)! 
Returns a matrix containing names, types, and sizes of files 
ina library. If an account number is givea, information is 
given only for the files that are public or semiprivate or 
for which the user has access permission. If a namo is 
given, detailed information about that one file is returned, 


Error Processing 


DITRAP integer 
Specifies that errors аге to bo intercepted by a forced 
branch to the specified line of the currentiy executing 
function. 


owen 


“KR is а 3-row matrix of the last error message, the line 
having the error, and a pointer to the position of the error 
in the line. 


natrix¢QSIY vector 

The result is a character matrix containing the rows of the 
ate indicator with variables display specified by the 
right argument. П5/У ipÜLC gives the entire display (in 
either origin). 


venre 
022 is a vector of`all line numbers appearing on the state 
indicator, 
= == 
Miscellaneous System Communication 
VAT 
UAI is a vector of accounting information. faz [1 2 3 а] 


gives: an encoding of the user's account number, accumulated 
central processor time, accumulated connect time, and 
accumulated keying time. 


уд 
< vector of all 256 APL characters. 


veors 
Zine stamp: current year, month, дау, hour, minute, second, 
and millisecond. 


venr? 
germinal type. 


Qwa+v 
Working area: CWA[1] is the part of the maximum field length 
available for use, CWA[2] is the current field length, 
QwAL2] and ПУА[&] are the minimun and naximun field lengths 
the user wishes APL tc use. 


‘command! 
ferninal mode: conmands aro SYSTEM, OF? and ABOA?, to return 
То KRONOS cormand processor, sign off, or abort batch job. 


S$+CDL seconds 
Causes execution to delay for the specified number of 
seconds. 


flowever, three system variables are so important that when they 
are undefined the system uses default values. Thus, when (РИ is 
undefined the system uses 30 as the printing width, When DPP is 
undefined, normal output uses а value of 1. When Oc? is 
undefined, the system uses zero as the comparison tolerance for 
demain tests, although numerical comparisons still cive implicit 
errors. For exemple, 


Dzx'Ocz! 


3 
01: IMPLICIT ERROR (Because DCT is undefined for comparison.) 


1 


123 
13+15712 

03: DOMAIN ERROR (Because ПСТ is zero for domain tests.) 
13+12 12 
4 


Certain system variables are not stored in the workspace. 
These session variables remain in effect if another workspace is 
loaded and always have their normal values when an АРІ session 
begins. “he session variables are OWA, OPZ, ОТТ, Ors, and Dkr. 


NAME LISTS 


Some system functions require arguments consisting of lists 
of names. In all cases such namo lists can be either a vector of 
nàmes separated by spaces, or à matrix of names with one name in 
each row. In either form extra spaces are allowed before or 
after names. When a system function returns a list of names as a 
result, the list is always in the form of a matrix because the 
matrix form is usually more convenient for manipulation by the 
program. 


WORKSPACES 


An APL workspace comprises variables, user-defined 
functions, the state indicator, and system variables that are 
currently defined, A clear workspace comprises the following: 


an empty state indicator 

022+10 (printing precision of 10 digits) 

Upw-120 (up to 120 characters are printed per line) 
ZCT-58711 (comparison tolerance is s£ 11) 

DI0-i (index origin is 1) 

D&85«16807 (random link is 16807) 

Dzvv+1 (local environment) 

ОЕкя-3 0р'' 


| 
р 
| 
| 
I 
i 
| 
ү; 
I 
i 
| 
I 
| 


In addition, the clear workspace also presently incl 
functions Jp (which performs function definition mode), 22: 
(which performs system commands), and the mixed functions 

T, and i. Although some of these may eventually become 
incorporated into the APL system itself (and thus be removed from 
the clear workspace), they presently occupy considerable space in 
active ané stored workspaces. See Caapter 11 to learn how to 
eliminate or restore these functions. 


As functions and variables are defined, they become part of 
the active workspace. А copy of an active workspace can be 
saved. To use it at 2 later time, a copy of the saved workspace 
can be activated (that is, made active). 


A stored workspace is a special kind of KRONOS "file." 
Under an account number (or user number) can be stored as many 
files as are allowed by restrictions imposed on the account 
number, The collection of files is known as a library. 


APL workspaces and data files are ordinarily KRONOS private 
files, which means that-other users cannot use them, A user my 
optionally save a workspace as a seniprivate file ог public fiie 
by use of commands of the form DSAVE 'пате/5' or OSAVE'name/PY'. 
This allows other users to access the workspace but does not 
allow them to alter it. Other users can bc given permission to 
access a private file by use of the KRONOS PERMIT control card 
(see Chapter 12). This gives selected user nurbers permission to 
access the particular file. Further details about these file 
categories can be found in Chapter 9 and Chapter 12. 


Passwords can be given to workspaces for additional 
security. When à workspace is given à password, other users must 
provide the password in order to access the workspace. However, 
the owner of the workspace need not provide the password in order 
to use it. 


The first time a workspace is saved it сап be given à 
password or a category (i.e., private, semiprivate, OF public. 
hereafter, the file password and category remain unchanged for 
subsequent’ save commands that replace the stored workspace. 
(Thus, the password and category options should not be proviced 
for subsequent save commands.) To change the password or 
category you must load the workspace, drop the stored one, and 
then resave it with the new options. Alternazively, you can use 
the CHANGE control card (see Chapter 12). 


Workspaces can optionally be saved in direct eccess form 
(ordinarily they are saved in indirect access form). This option 
is chosen by using a command of the form USAVE'name/DA' the first 
time the stored file is established. Direct access workspaces 
are faster to load, save, ох copy, but require more disk space. 


The direct access option is appropriate for unusually iarge 
workspaces that are loaded or saved very often. А workspace can 
be changed to direct access form by loading it, dropping it, 
then resaving it using the ра option. 


Workspace names must begin with a letter, which may be 
followed by additional letters and digits. However, the name 
must not exceed seven characters. Passwords may consist of 1 to 
7 letters or digits, 


NOTATION 


Throughout this chapter, brackets are use@ to surround 
optional portions of expressions. ‘The brackets themselves should 
not be used. For example, 


DLOAD '[*account] wsname [:раззча |" 


means that the account number and password are optional. Any of 
the following commands are of the correct form: 


DLOAD ‘ALGEBRA’ 

DLOAD '¥A123456 ALGEBHA:SESAME' ] 
DLOAD 'ALGESRA:SESAMB' 

QLOAD '«4123555 ALGEBRA" 


SYSTEM VARIABLES FOR OUTPUT CONTROL 


Printing precision.  DPP«integer (1 tc 15) 

The value of OPP determines the maximum number of significant 
digits to be used for numeric output. The result is rounded to 
[PP digits; hence if DPP is 3, 0.34567 would be printed as 
0.346. See Appendix B for further details of numeric output 
format. 


Printing width. OPW+integer (30 to 71+2*17) 

The valde of При determines the line width used for output. Wien 
a line of output requires more character positions than DPW, the 
remaining characters are indented and continued on successive 
lines. Output of numbers will not cause individual numbers to be 
split between two lines, but output of character data 
representing numbers may cause numbers to be split between lines, 


Print lines. OPL+pagesize, linecount 

DPE is primarily intended to facilitate the use of CRT terminals 
having a screen smaller than the total amount of output 
generated. Appropriate setting of JPE causes output to pause 
when the screen has been filled to allow the screen to be 
examined or cleared (if required) before more oucput is sent. 
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The first element ОЁ JPL should be set to the number of lines 
that will be used for actual output. The second element of [9L 
is a count of the number of lines actually used for input and 
output. When each output line or input line has been completed, 
OP£€2] is incremented by 1. — 1f Пгр[11#0РЕ[21, the system prints 
? om the next line and suspends further output until RETURN is 
pressed. (Any other input is treated as if RETURN has been 
pressed.) The program requesting input can be halted by use of an 
interrupt (see Appendix С). When RETURN is pressed, OPL[2] is 
reset to 0, and further output is sent. The value of []PLf2? can 
be reset to compensate for screen repositioning caused by graph 
mode output. The elements of DPL are restricted to positive 
integer values. If an attempt is made tc set DPL[1] to 1, it 
actually is set to 0. I£ the last line on the screen is used for 
input, the ? is suppressed and normal input can be entered on 
that line. (The input request gives a pause to allow tke screen 
to be read.) 


IPL has a different meaning when APL output is sent toa 
file rather than to »a terminal. Specifically, if APL is not 
being used from a terminal or is being used from a termina) but 
the output file name is not OUTPUT, ала if the shifted output 
option is in effect (see Appendix D), a page eject carriage 
control character is sent at the beginning of the next output 
line whenever the page size has been exhausted, 


VARIABLES APFECTING PRIMITIVE FUNCTIONS 
Comparison tolerance. QcT«number (0 to .01) 
La comparison tolerance is used when comparing numeric values 
and when testing whether values are sufficiently close to 
integers: 
1l. Two numbers A and B are considered equal only if 
(1А4-В)5)ПСТхВ 


2. А number 8 is considered tc be in the integer 
domain if 


(ротар в)-в)5ет+1Остхитит 8 
where NINT Р is the nearest integer to 2, defined by: 


ZANIN? B 
[1] Z-OB)xL. 5+ [87 


The value actually used for the operation is XIN? 8. 
If 007 is undefined, zero is used as IcT. 


Random lin! ORLteinteger (1 to ~1+2447) 

RL determines the next random number to be produced by roll or 
deal. Each time a random number is requested, the value of NRL 
changes. A series of randon numbers can be recreated by setting 
075 to the same initial value and repeating the same requests. 
Because the value of DRZ is saved with the workspace, it may be 
desirable to reset it after the workspace is loaded to a value 
based on the current tine of day so that the random numbers 
produced 11 not be the same as for the last session; for 
example, URLe*/CTS. 


Index origin. Г10+6 or 1 

The Index o; Origin determines the origin for counting coordinates 
or elements along coordinates. In O-origin the elements of a 
vector would be numbered 0, 1, 2, etc. А11 indexing should use 
values that аге 1 less in 0-огідіп than in l-origin. In 
addition, the following functions produce results that are 1 
less in Q-origin than in l-origin: A15, iB, 48, 78, А?В, and, ?8, 
In addition, the left argument for dyadic transpose should be 1 
less for 0-огідіп, and all axis operators require values that аге 
1 less. That is, x should Бе l less in expressions like A/LX18 
and $[X)2. * 


FUNCTION DEFINITION 


Environment. DE¥/+0 or 1 

ТЕРУ controls whether the functions (cr, OFX, DEX, ONC, ОЕ» 
DLTIME, ПМАМЕ5, OCOPY, DOSTOP, DLOCK, and ОТВАСЕ refer to the 
global environment or to the current environment. Wher Dewy is 
0, the global environment із used, and when Qewy is l, the 
current environment is used. “he normal value of [EWY is 1, so 
the system functions listed above nay refer to local variables 
and functions. However, | when function definition mode is 
entered or when a system command is performed, only the global 
functions and variables are used. When the state indicator is 
empty, the current environment and the global ervironment are the 
same and DENV has no effect. 


Canonical representation matrix+QCR ‘name’ 

Canonical representation returns a character matrix 
fepresentation of a function. “he right argument contains а 
character vector or scalar containing the name of the function to 
be returned. The result will have one row for cach line of the 
function, including the function header. Lines will be indented 
one space unless they have labels or begin with a comment. If 
the argument does not name a function in the environment 
specified by (ЕМУ, a NAHE NOT FOUND error ie given. If the 
function named by the argunent is locked, the result will have 
0 0 as its shape. 


Pix. 2+QFX matrix 
ÜFX establishes the function represented by the character matrix 
argument. If the attempt to establish the functicn is 
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successful, z will be a vector containing the 
function, ^ Replacemeht of previously exiseing бш 
allowed and may result in SI DAMAGE if she functio 
The SI DAMAGE error is processed as a normal error, excep: 
if the state indicator entry for the currently executing function 


was damaged, error trapping is not allowed to take place. Та 
this case the error is considered to be located at the last line 
entered in immediate execution mode, DFZ cannot be used to 


replace objects other than functions, An attempt to establish a 
function пау also fail as а result of an incorrectly forned 
function header or duplicate use of statenent labels or iocal 
variables. If the attempt fails, 2 will contain a scalar row 
index of the linc that was improper. Functions created by Fx 
can be declared local to other functions. 


Expun: 1+ПЕХ 'names' 

le. xpunges (erases) functions and variables named by the 
argument. the result 2 is a logic vector containing l's in 
positions corresponding to names in the argunent that are now 
free, and 0's in positions corresponding to names that remain 
unavailable for new uses. Erasure of a function that is on the 
state indicator does not take effect until the function is no 
longer on the state indicator. Thus a function can erase itself 
and not actually be erased until it exits. The unfinished 
execution can complete, but the name is immediately available for 
new uses. 


Name class. vector+{WC 'names* 

LC returns information about use of the names in the right 
argument. The result 2 contains 0, 1, 2, 3, or 4 according to 
whether the name is available (not in use), 2 locked variable 
(label or group), unlocked variable, a functior, or other (i.e., 
a defined distinguished name), respectively. Incorrectly formed 
names in the argument cause a DOMAIN ERROR. 


Name list. matrix«DEL Y or Z-'letters' DNL V 

The name list functions return lists of names in use. The right 
argument is a numeric vector such that ^/Vel1 2 3 4. V indicates 
the classes of names for which information is desired--1 for 
locked variables (labels or groups), 2 for unlocked variables, 3 
for functions, and 4 for distinguished names. The result z is a 
matrix of the nanes. The left argument of the dyadic form may 
contain any number of letters, and names appear in the result 
only if they begin with those letters. 


Lo vector«DLOCK 'names! 

The variables and functions specified by the right argument arc 
lecked. A ‘locked function cannot be displayed, and a locked 
variable cannot be reset using specification, (However, a locked 
variable can be reset by erasing it and then usin 
specification.) Locking a variable is a very useful way to fing 
where the variable is resec. When the variable has been locked, 
the next assignment to it will cause an error halt. Label 


ups are automatically locked to prevent them 
“Proper values. ne result returned by DLOCK 
in positions corresponding to names that are now 
locked end contains 0's for other names. 


STOP, TRACE, AND TIMING CONTROL 


The functions CSTOP, ПТВАСЕ, and ОРТТИЕ are closely related. 
In each case the right argument is a character vector or scalar 
that names a function, and the left argument for the dyadic form 
must contain nonnegative line numbers for which the control is to 
be set. Setting controls for any lines clears all controls of 
the same type for the other lines of the function. Elements of 
the left argument not in the range o£ line numbers are ignored. 
In all cases, an empty vector of line numbers can be used to 
Clear the controls, An empty character vector is allowed as a 
left argument for notational convenience (e.g., '' OSTOP 'PLO?'), 
The monadic forms of the functions return information about 
controls that are currently set. 


Stop control. V DSTOP 'name' and 205102’ лаше* 
When the stop control is set for a particular line, execution of 
the function suspends before execution of the line begins, and 
the system prints STOP SLT, the name of the function, and the 
line number. To continue execution where it stopped, issue a 
branch to the line number just printed. Stop control at line 0 
of a function causes suspension just prior to exit from the 
function. The monadic form returns a vector of line numbers for 
which stop controls are currently set. 


Trace control. У ПТААСЕ ‘name’ and 2+]?#АСЕ ‘name’ 

Setting trace control for a line causes the function name and 
line number to be printed each time after the line has been 
executed, and if the result of the ‘line was used for a branch ог 
assignment, the result is printed even though it ordinarily would 
not be. Setting trace contol for line 0 causes tracing of the 
exit from the function and causes printing of the explicit result 
of the function (if it has one). The monadic form returns a 
vector of line numbers for which trace controls are set. 


Line timing control. V ULTIME 'name' and 2+QLTIMNE ‘name’ 

Setting the line timing control for a line causes the Central 
Processor tine for that line to be accumulated. The time for а 
line is accumulated until line timing con:tols for the function 
are reset, at which time all accumulated times are set to zero. 
An attempt to set line timing control for line 0 of a function 
causes a DOMAIN ERROR. ‘The result returned by the monadic form 
is a 2-column matrix--the first column contains the line numbers 
for which the line timing control is set, and the second column 
contains the total times for the lines. Because the time clock 
has a resolution of one millisecond, each parcel of time used by 
the line is measured with limited accuracy, and lines consuming 


very little time or lines consuming time іл small parcels can b 
expected to show relatively large cczracy in accumulate 
times. Nole that the times accumulated for a recursive functio 
сап count the time more than once. 


PROGRAM LIBRARIES 


Workspace identification.  QWSIDe'nane* 

The variable 09510 contains the nane of the active workspace 
The name of. the active workspace is used as the name for storin 
the workspace if no name is specified when [ISAVP or )SAVE i 
used. The name must begin with a letter, which may be followe 
by additional letters or numbers. No spaces are allowed withi 
the name, but spaces may precede or follow the name. The nam 
must not exceed ssven characters, 


Save. ZeDSAVE ' wsname [:passvdl[/options]' 
USAVz saves a copy of the active workspace under the specifie 
nare and attaches to the saved workspace the password :f one i 


used. If a password is used, it must be separated from the nam 
by а colon. The name itself may be omitted, and in this case th 
value of [WSID is used as the name. When [save is executed fro 
a function, the state indicator of the saved workspace will sho 
suspension where [SAVE was executed. The options may include $ 
P, or PU (for semiprivate, private, or public category) or ma 


include DA or 14 for direct access or indirect access. The lis 
of options may include any desired number of options, separate 
by spaces, as long as the options do not include contradictor 
choices. The options and password may be specified only when th 
saved workspace is first established. ^ If no options ar 
specified, the workspace is saved аз a KRONOS indirect acces 
private file if the saved workspace is being created: otherwis 
it is saved in the same form as before. 


The result returned is a vector of the workspace лале an 
the current date and tine. However, when SAYE is used i 
immediate execution mode, the name, date, and time are printe 
rather than being returned as a result. 


Dyadic save. А (SAVE ' wsname (:passwdJi/options}" 

The dyadic save function is like the monadic form except that 
permits control over the state indicator in both the active an 
the saved workspace. Тһе argument 4 may be а numeric scalar o 
vector. If A is 0, a clear state indicator results, and if à i 
l, the state indicator is backed up to the point of che nos 
recent suspension (or cleared if there have been no previou 
suspensions). Note that a function calling the dyacic [sav 
function always ceases to execute because of the change in th 
srate indicator, unless ап error prevented completion of th 
operation. Dyadic save prints the workspace name ond the curren 
date and tine. 


Latent expression. (ix+' expression’ 
The latent expression in a workspace is executed immediately when 
ne workspace containing it is loaded. When a workspace has по 
latent expression, the keyboard unlocks for the user to specify 
the first operation to be performed. A successful load operation 
ordinarily causes the time and date when the workspace was saved 
to be printed, but when the workspace contains a latent 
expression this message is absent. 


Load DLOAD '[*accouat] wsname (: passwd]! 

The function DZ04D activates а copy of a stored workspace. “he 
right arcument must contain the name of the workspace to be 
loaded, the password for the workspace (i£ it requires one), and 
the account number under which the workspace is stored (if 
different from the user's own). А successful load results in 
execution of the latent expressicn if the workspace being loaded 
has one. If the workspace has no latent expression, the tine and 
date when the workspace was saved are printed. 


Name list for stored workspaces. gatrix=V QWAMES '[*account] 
wsname .:passwd]" 

The OWAMES function returns a matrix list of the names used in a 
stored workspace. The list returned is controlled by (ЕМУ in the 
active workspace. The right argument is the same as the right 
argument for DLOAD. The vector V may contain the integers l, 2, 
3, or 4 to specify what classes of names should be 
returned--locked variables (labels or groups) if iev, unlocked 
variables if 247, functions if эсу, and distinguished names if 
чет. 


Monadic name list. matrix+UWANES'[*account] wsname [:passwd]' 
Returns a matrix of names of all objects in thé workspace or a 
vector error message. Sane as dyadic form with 1 2 3 as a left 


argument. 


Copy. macrix+'names' ГССРҮ 'Craccount] wsname [:pasgwd]! 

The function ССОРУ copies functions and variables from a stored 
workspace to the active workspace. The account number, workspace 
name, and password are the same as described for DLOAD. “he list 
of names in the left argument specifies objects to be copied. 
However, lf copying the object would cause replacement of objects 
already in the active workspace, the copying process is 
inhibited. If DEWY is zero, copying will be from the global 
environnent of the stored workspace to the global environment of 
the active workspace, and if DEWV is 1, the current environments 
will be used. The result from 0СОРҮ is a matrix of names of 
objects not copied because they were not found, because №5 FULL 
occurred, or because they already were in use in the active 
workspace. 


Monadic co error+0CUPY '[xaccount] ssname (passwd! 
Like dyadic copy except that all objects of classes 1, 2, and 3 
{see DWC) are copied. 


Drop. erroz*ÜD20P '[*accoant] излале [:passwd]' 

"he function “PROP removes a stored workspace (or other KXONOS 
file) from the user's library. A password must be specified if 
an account number is specified and differs fron the one used to 
sign on to the system and if the file has a password. 


Library list. iist+Q&IB 'i*account] [nane] ' 

The function LIP returns the names of files stored under the 
specified account number {or the user's own account number if го 
account number is specified). The list is a matrix such that 
each row has the following fields: 


File name: 7 characters 
File type: 2 characters 
File size (in words}: 6 characters 


One space separates adjacent fields. When a file пале is given, 
detailed information about that particular file is returned. The 
format when a name is provided is illustrated below: 


DLIB'«APLi PILESYS" 
FILESYS WS 2059 


145 RD 

75/08/12 12:45:58 (When created.) 
75/05/30 13:03:30 (Last change.) 
75/07/31 12:30:59 (Last access.) 


Che first row gives the name, type of file (WS for workspace, Р 
for APL file, blank for all others), and the size in words. The 
second row indicates the file is indirect access (the other 
possibility world be DA for direct access), the file category 
(S for semiprivate, P for private, anā РИ for public), and the 
mode of access permitted for other users, (20 for read, WR for 
write, КИ for read-modify, MD for modify, A? for append, RA for 
read-append), 


ERROR PROCESSING 


Some system functions respond to certain erroz conditions by 
xetarning a result to indicate the error. ^ However, APL handles 
most errors by suspending execution at the point of the error, 
printing a message, and unlocking the keyboard for a new command 
to be entered. Note that a keyboard interrupt (see Appendix C) 
is treated аз an error, аз is typing @ (0, BACKSPACE, V, 
BACKSPACE, Т). However, halts due to step controls are not 
errors, | Special exceptions arise when the error is in ап 
argument to the execute function, in a quad input entry, in a 
locked junction, or when ОТВАР has been used to intercept errors. 


Errors in an argument to the execute function normally cause 
two error messages to be printed. The first shows the execute 
argument, and the second shows the error at the line where 
execute was called (more precisely, the most recent pondent line 
other than lines of locked functions or arguments to execute). 


Errors in lines entered for quad input cause the request for 
input to be repeated. If the error was encountered in a function 
called by the input line, the request for input is not repeated 
ала normal error processing ensues. 


For security reasons, lines of а locked function are not 
shown in error messages. Any error in a line of a locked 
function is treated as if it were situated in the line where the 
locked function was called (more precisely, the most recent 
pendent line other than lines of locked functions or arguments to 
execute). 


The function ОТВАР can be used to designate a lino of the 
currently executing function to intercept errors. Once this has 
been done, error trapping is in effect and an error in any line 
of the function causes a forced branch to the trap line. The 
error trap is in effect for functions called by that function or 
for functions that are in turn called by those it calls, etc. 


whe scope of error trapping is analogous to the scope of 
local variables. A function with @ trap line remains in control 
of errors unless a function called by it sets its own trap line. 
The newer trap line takes precedence over the old one until the 
called function completes execution or clears its trap. The trap 
also takes precedence over the normal processing of errors in 
quad input lines. 


When a workspace is loaded, an interrupt nay be acted upon 
as an error before the latent expression has been executed anc 
the error trap has been enabled. То prevent this situation, а 
function with a trap can be halted using a stop control before 
the workspace is saved. The latent expression can then 
deliberately cause an error in order to invoke the trap line. 


Error matrix. ÜERR 

"he character matrix СЕРВ contains the last error message. Row І 
has the type of error. Row 2 has the name of the function 
(truncated to 8 characters for long names) the line number 
(surrounded by brackets), and the line itself. Row 3 of DERR has 
a slash to indicate where the error was found in row 2. Тһе 
number of columns in ПЕРА varies according to the longest of the 
three rows. 


me first row always shows the type of error actually 
encountered, but the location of the error as shown in rows 2 and 
3 can be different from the actual location of the error undez 
the following conditions: 


1. If error trapping is in effect, the error is treated 
аз an error in the pendent line of the trapping 
function. 


2. If error trapping is not in effect апа the error 
occurred in a line of a locked function or in an 
argument to execute, the location of the error is 
considered to be the most recent pendent line chat is 
not ап argument to execute ora line of a locked 
function. However, an error іп a locked function that 
uses trapping causes [gar to contain a line of the 


locked function. It is advisable for the locked 
function to localize (ga? in order to protect its 
security. 

Trap set. ОТВАР integer 


The ОТРАР function sets, resets, or clears the trap line for the 
currently executing function. Use of DTRAP from immediate 
execution mode has no effect. The argument must be an integer. 
If the integer is within the range of line nuxbers, that line 
becomes the trap line." If the number is 0 or exceeds the number 
of lines, trapping causes exit from the function, The trap can 
be cleared by [7RAPi0. Once trapping is in effect, an error іп 
that function, in D input, or any function invoked by іс causes а 
forced branch to be taken to the trap line, and the trap state is 
cleared. Note that Offs? must be used to set tho trap again 
before additional errors can be intercepted by that function. 
Hence a second error during processing of the trap routine 
results in either normal error processing or error processing by 
а function that invoked this one. If trapping is in effect, 
execution of functions can still halt as a result of & stop 
control. However, the trap then remains in effect Zor errors in 
imaediate execution mode. 


When a forced branch to the trap line occurs, at least one 
function will execute before an interrupt is detected. For 
complete security, the trap line can immediately reset the trap. 


Location counter: ЦС 

The variable TE contains а voctor'of all lina numbers appearing 
on the state indicator. The numbers appear in the same order as 
in the )5гу display--that is, the numbers of the most recently 
invoked lines appear first. The first element is the number of 
the function line currently executing. 


State indicator and variables. matrix-[STV vector 
The function DSIV returns rows of the state indicator, including 
local variables. The argument must be a vector or scalar 
containing integers. The value returned is a character natrix 
containing а portion of the )SIV display selected by the right 
argument. 0577 1062 prints the entire SIV display (іп either 
origin). If a value іп the argument exceeds the range of 
appropriate row indexes for “he 577 dispiay, а blank line 
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appears in the corresponding row of the result, Xote that only 
entries or function lines appear on the state indicator--aot 
arguments, guad input lines, or inmediate execution 


MISCELLANEOUS SYSTEM COMMUNICATION 


Accounting information. [MT 
The variable UAI is a numeric vector of the following accounting 
information: 


04111) - A numeric encoding of the user's account number. Рог 
a character vector У containing the 7-character account 
number, the value of D4I[1J is generated in one origin 
by 1001'ABCDEFGHIJKLMNOPQRSTUVVXYZ0123956789'iV 

Пас: - Central processor tima used. 

04113) - Total connect time. 

arts) - Total time the keyboard has been unlocked. Includes 


part of the time required for the systen's response. 


Times are in milliseconds and are cumulative since signing on to 
АРІ. 


Atomic vector. (MV 

The vector ПАУ contains all 256 characters manipulable by APL. 
The ordering is such that the first 128 characters are in ASCII 
order. Note that the ordering of characters in DAV is system 
dependent, and programs that depend on the ordering of characters 
in DAV cannot be easily transferred to other APL systems. “See 
the table in Appendix С to find positions of particular 
characters. 


Time stamp. 075 

The value" of (T is а 7-element numeric vector expressing the 
current point in tine. The elements are in the following order: 
fhe year (е.9., 1975), month (1 for January), day of the month, 
hour (0 to 23), minute, second, and millisecond. The last 
Qlement is always 0 because the operating system does not report 
the time of day to millisecond precision. 


Terminal orr 
The value of ОТТ identifics the type of terminal in use. The 
value is a numeric scalar as follows: 


- Correspondence 

= Type-pairing 
Bit-pairing 

- ASCII-APL 

= Teletype Model 33 


ПРСТА 
' 


= Pull ascii 

- Batch ASCII 

> Batch 501 Printer 

- Teletype 36, arrangement 


ouo 


Мог. grea. [WA 

"he value of (ид is а 4-element vector о! the part of the 
maximum field length available, the current field length, the 
minimum field length the user wishes used, and the maximum field 
length the user wishes used, The field leagth is the actual 
memory space occupied by the APLUM system and the workspace, The 
user can set constraints on the field length to be used in order 
to optimize performance (see Chapter 11). Attempts to reset the 
first two elements of OWA have no effect. The maximum field 
length cannot be set to less than that which is currently 
required. Setting was] to more than the user's validation 
limit (see Chapter 12) or more than the field length limit 
imposed by the computer operator may actually increase the chance 
of a WS PULL error. 


ПРМ! command! 
mode function allows the following operations: 


Terminal mod 
The terminal 


ÜTM'SYSTEM' Returns control to the KRONOS command 
processor. 


ӨТМ'ОЕЕ! ^ Signs the user off. 


DZM'ABORT' Terminates job with KRONOS abort error fla 


E 
a 


Note that these commands do not cause the active workspace т 
saved, 


Delay. 2-00 seconds 
Causes execution to delay for the number of seconds гез 
The delay does not involve consumption of Centra? Processar time. 
The result returned is che actual delay that occsrr 

slightly more than requested). Тһе delay cannot be 


| 
1 
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Chapter 8, System Commands 


System commands in APLUM provide the same capabilities as 
some of the system functions and variables. “he system commands 
are provided for compatibility with other APL systems. There are 
бопе advantages to usiñg system functions and variables instead 
of system commands--the system functions and variables can be 
used in programs (system commands cannot) and system functions 
and variables are nore efficient. For more complete discussions 
ОР the operations performed by system commands, see the related 
system functions in Chapter ?. 


GROUPS 


The APLUM system, unlike some other APL systems, does not 
have a distinct data type for "groups." However, the APLUM 
system commands allow a character matrix of names to be used for 
the same purposes as groups in the other systems. Рог example, 
if GRPX is а matrix of names, the command )ERASE .GRPX would 
erase GRPX and any objects referenced by the names in GRPX. “he 
period in the command is required to indicate that objects 
referenced by САРХ are to be erased, not just GPx itself. The 
general system convention for distinguishing groups is that ali 
group names should begin with САР. Matrices of names that do not 
begin with G#P can be used as groups, but they will not be listed 
by the command )GRPS. The names in the group definition can be 
preceded by a period, which causes them то be interpreted as а 
reference to another group. 


)CLSAR (Equivalent to NLOAD'sAPLO CLEARS") 


mhe command CLEAR activates a clear active workspace 
(described in Chapter 7) and erases all indirect access files and 
unties all direct access files. 


Summary o£ Chapter 2. 


ОШАЙ 
activa: 

)BRASE nanes 

Zrases specified functions and variables. 
VE fwsname] [:passed) (/options] 
Saves a permanent copy of the active workspace. 

)LOAD L«account) wsname i:passwd. 
Activates a copy of the specified workspace 

)bROP [waccoune] wsname [:passsd] 
Removes a pernanent vorkspace from the library. 

)COPY [*account] wsnaze [:passwd] [names] 
Protected cop; of all global objects of classes 1, 2, and 3 
or selected global objects from a stored workspace to the 
active workspace. 

)UCOPY {тассоопе] wsname [:passwdl (names) 
Unprotected copy of all global objects of classes 1, 2, and 
3 or selected global objects from a Slored workspace to the 
active workspacc. 

)LIB [*account) (паве) 
Displays nanes, types, and sizes of all files, or displays 
detailed information about a single file 

)83STEH 
Returns control to KRONOS command processor. 


s à Clezr workspace. 


› 


OFF 

Signs a user off. 
81 

Displays the state indicator. 
)8ТУ 


Displays the state indicator along with names of variables. 
JPNS [letter] 

Displays names of functions. 
)YARS lietter] 

Displays names of variables. 
ERPS [letter) 

Displays names of groups. 
САР group-name 

Displays names in a specified croup 
)GROUP group-name names 

Forms a group having specified names. 


)ERASE nanes (Equivalent to [FX 'names'] 


Erases all global objects specified by the list of nenes. 
If а name is preceded by a period, the name is treated as the 
nane of а group. The erasure erases the group itself (actvally a 
matrix of characters) and the objects referenced by the group. 


SAVE — ([wsname] (:passwa} [/options: 
(Equivalent to USAVE '(wsnamcl asswd] C/options}') 


The )647Е command saves a copy of the active workspace under 
the name specif or ander the name in [252 if no name is 
given, 


1L0AD Lxaccount) wsname U:passwdl 
(Equivalent to 0204р '[*account) wsname [:passwd]!) 


The )LO4D command activates a copy of a stored workspace. A 
password is required if the workspace лаз a password and із 
stored under another user number. After the workspace has been 
loaded, the system executes DAX if OLX is defined. 


)DROP [*account] wsname [: passwd] 
(Equivalent to 2280Р 'l*account] wsname Ü:passwd]') 


The )DROP command removes a stored workspace ог other XROUOS 
file from a library. If the workspace is in another user's 
library, a matching password must be given if the stored 
workspace has a password. "he user must also be authorized to 
alter the existing file. 


wai inames? 


)COPY [«account) wsaame [: 
wd] [names] 


)UCOPY *account] wsname (:p. 


тһе )COPY command performs a protected сору of global 
functions and variables from a stored workspace ta the active 
workspace. “he )COPY command will not replace objects in che 
active workspace with objects from the stored workspace having 
the sane names. The )0С0Р? command performs an unprotected copy 
and will replace objects having the sane names. If no list of 
names is given, all objects of classes 1, 2, and 3 arc copied. 
Tf а name in the list is preceded by a period, the пале із 
assumed to refer to a group and objects named in the group are 
also copied. The ПСОРУ function can be used instead of )72 
groups are not to be copied. The form is ['zames') 
"[*account] wsnamo [:passwd]'. 


LIB [«aceount. (name! (Equivalent to 0518 '[+account]iname]') 


The )LI3 command displays names, types, and sizes 
files the user is authorized to access, ог, if a file гапе is 
specified, LIB displays detailed information about that 
particular file. The format is tho зале as for CLIR (see Chapter 
л). 


)SYSTEm (Equivalent to DTN'SYSTEN') 


The command )575Т5М causes the user to leave APL control and 
allows the KRONOS command processor to execute subsequent 
commands. “The active workspace is not saved. 


)OFP (Equivalent to П?М'ОРР') 


‘the )OPF command signs a user off the system. 


EH 
317 (Equivalent to DSIY 10020) 


The comand )SI lists the state indicator, and the command 
)SIV lists the state indicator and all local variables. See 
Chapter 2 for the format of the display. 


)FNS [letter] (Equivalent to OFL 3) 
JVARS [letter] (Equivalent to DL 2) 
)GRPS [letter] (Roughly equivalant to '%' DWE 1) 


These commands list the names of defined global functions, 
variables, апа groups, respectively. Ifa letter is included, 
only names beginning with that letter or letters that follow that 
letter in the alphabet are shown. Тһе conrand )GRDS lists 
variable names that begin with GAP. 


)8POUP group-name names 


The comand )GROUP defines a group, extenós а group, ог 
erases a group definition. Groups are actually represented as 
character matrices. If the group-name itself is the first nane 
in the list of names, any previously defined group is extended by 
the addition of the remaining names. If no names aro given, the 
group definition is erased but objects named by the group are not 
erased, Manes listed in the command can be preceded by a period 
in order to include a period in the group definition (to indicate 
tha nane refers to another group). 


GRE grpnana (Squivalent to grpname) 


The command )CAP displays the Gefinition of th 
group. I£ the group is not defined or is not s character 
àr error message is given. 
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Chapter 9. File System 


This chapter discusses files from the APL user's point of 
view. The APLUM system supports two distinct types of files: 
APLUM files, and KRONOS coded files. The use of files enables 
programs to deal with large quantities of data that would not fit 
into a workspace, and files also provide a convenient way for 
programs to communicate with one another. 


Further information about KRONOS files can be found in the 
KRONOS 2.1 Reference Manual, 


APLUM FILE CONCEPTS 


An APLUM file is a collection of APL arrays with each array 
identified by a nonnegative integer. The following example shows 
creation of a file and writing and reading a few records (arrays) 
of the file. 


)LOAD жАРЬ1 FILESYS (File system functions are 
loaded from APL1.) 


"SAMPLE! FOREATE 9 (Тһе FCREATE function is used 
to create a file with the name SAMPLE 
and with 9 as its number, ) 


"КЕСОКЫ 3' FWRITE 9 3(The left argument is written 
to file 9 as record 3.) 


(3 3p19)FWRITE 9 1 


(2 3e'D') FWRITE 9 28 

PREAD 3 1 {The records can be read in 
123 any order.) 
"55 
78389 


Summary of File Functions, 


"D^account] filename [:passwd] [/options]! PCREATE fnum 
Creates а file. Options are DA, С, WR, S, Or PU. 


array РЮРІТЕ fnun[,rnum] 
Writes array on file number fnum as record глив. 


result-PREAD fnuml,znum] 
Reads the record numbered глиш fron the file numbered faum, 


PRDEL fnam[,rnum] 
Deletes record rnum from file fnum, 


rnumeFPRES fnum 
Returns the least record number not presently in use ir file 
fanum. 


PPOS fnum,rnum 
Sets position of file fnum to rnum, 


result+FSTATUS fnums 

Returns the status of all files specified by the right 
argument, The result is a vector or matrix according to whether 
the argument is а scalar or vector. Columns are: (1) largest 
record number, (2) current position, (3) file size, (4) unused 
space, (5) lost space, (6) space not used because record sizes 
not divisible by 64, (7) 1 if coded file, (8) 1 if DA type, (9) 
1 if absent record encountered by last read attempt. 


PSTATUS 
Prints status information (with discriptive headings) for 
all active files. 


result-PNAMES 
Returns a matrix of user numbers and names for all tied 
files. 


result-FlüUMS 
File numbers in use for tied files. 


FPRETURN fnums 
Unties specified direct access files and erases specified 
indirect access files, 


FUNTIE fnums 
Unties files in right argument. This leaves а permanent 
copy. 
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PERASE fnuas 
Erases all files specified by right arqucent. Fras 
affects active file and for DA type also affects permanent file. 


!'[*account] file ле [:passwd] [/options]' FTIE faun 

Ties а file with specified options--ap for read only (other 
users can read at the same time), and py for read-modify (another 
user can modify at the same time). 


resulteCPRBAD £num 
Coded read. Result is character vector or numeric scalar--l 
for end of record, 2 for end of file, 3 for end of information. 


array CFWRITS inum 
The left argument is written to the coded file fnum, The 

argument should be a character scalar, vector, or matrix, or 

integers--1 to write erd of record or 2 for end of file. 


integers CFPOS fnum А 

Positions file. Operations indicated by first integer are: 
0 for rewind, 1 for skip record, 2 for skip file, 3 for skip to 
end. Second integer for skip record or skip file may be included 
as repetition count. 


jobname-CSUBMIT fnum 
Submits the coded, indirect acc 
and erases the active copy. 


file fnum as a batch jcb 


FREAD 9 28 
пос 
000 


PREAD 9 3 
RECORD 3 


After the above steps, the user can store the file (using 
FUNTIE 9), an operation analogous to saving a workspace. The 
user could then sign off the system, The information in the file 
would remain intact and could be accessed or modified at a later 
time. 


File limits. Individual File records are allowed to be as large 
as desired. However, user numbers have associated restrictions 
that may limit the total number of files, the total size of all 
files, the size of individual files, and whether the user can 
create direct access files. This information must be obtained 
from the installation or by executing the LIMITS control card 
(see Chapter 12). 


Tied files. 16 is usually more convenient to use numbers within 
а program to identify a file rather than using the file nane. 
Ali file operations require this file number. The number is tied 
to the file when tke file is created using FCRZATE or when a 
previously stored file is accessed using the ЕТТЕ function. Once 
a file has been assigned a number, the file is said to be tied. 
The file can be released by using the ryxTis operation, the 
FRETURN operation, by erasing the file using F*4AS?, by signing 
off fron APL, or by typing )CLEAR. However, files remain tied 
when another workspace is loaded. 


Accessing file functions. The functions described in this chapter 
are ordinarily stored under the user number 4PLi in the workspace 
FILESYS. Before file operations can be performed, the functions 
must be obtained from APL1 by loading ‘he entire FILESYS 
workspace or by copying selected functions from FILESYS. А11 
functions in FILESYS are independent, and you need copy only 
those functions you intend to use. The following examples show 
various ways that copies of the file functions can be obtained. 


)LOAD «APLi PILESYS 
02042 '«APLi PILESYS' 
XCOPY «APLi PILESYS .GRPPRIM (A group that excludes 
documentation) 
)СОРҮ xAPL1 FILESYS PTIE PREAD 
Thé file functions use the system function 027 to perform 
all file operations. The function DPI could actually be used 
directly, but it is usually more convenient to usc the functions 
in the 2705575 workspace. Most of the functions in the FILZSYS 
workspace are locked so that error processing will be more 
convenient, Users who wish to learn how to use Орг directly can 
Giscover all details about ОРГ by studying the definitions of the 
locked FILESIS functions below: 
VA FCREATE B [i] A DPI 1,89 
va FWRITE B [1] А (РГ 2,89 
VECFREAD B [1] 2<DPI 3,87 
VPESASE B [1] В Ort uv 
VERDEL B (1) OFI 5,87 
#2-Р5ТАТУ8 B [1] <В NFI 6V 
TZ-RHAMES [11 ZeDPI 79 
VOeRHUMS [1] 2001 av 
УРИИТТЕ B [1) B UFI 97 


vA PTIE B [11 A DFI 10,89 
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205 B [i] UST 11,99 


it] 4 OFF 12,84 
V2ZeCPRESD B 11] ZPE 13,89 
VA CFPOS B [12 DEF 18,B,A9 
9®+С50Ви1Т BCA) 2-CPI 15.89 
92<PFREF В 017 Z+OFI 16.8% 


In addition to the basic functions in the 216215 workspace, 
the workspace Р/ЬЕ82 contains additional file functions that are 
based on the functions in 21068375 and perform more complicated 
operations. 


Active and stored files. APLUM files are ordinarily xKxONOS 
indirect access files unless the user specifies otherwise at the 
time of creation. This means that when the file is tied, the 
system makes a copy of the stored file. All reads and writes 
actually interract with this active copy. То save the file as а 
permanent stored file, an FUNTIZ is required. Signing cff from 
APL, typing CLEAR, ог a telephone disconnect (assuring the 
RECOVER command is not used) causes the active file to be erased. 
One advantage of having a separate active copy is that no damage 
can be done to a stored file if a series of file updates is not 
completed. For example, suppose that a progran writes a record 
to indicate that a transfer of funds was made from one account to 
another on a certain date, then the program revises two records 
containing the balances of those accounts. I£ the program were 
to halt in the middle of the sequence of operations (due to a 
system problem ог telephone disconnect), the transactions 
recorded in the file would be inconsistent with the balances in 
the file. This causes no problem when indirect access files are 
used because the inconsistent information is in a temporary file 
and the stored file is in the same state it was when it wes tied. 


For some applications that use indirect access files, it say 
be desirable to perform an fU#TIZ and ап FTIE at intervals cf 
about every ten minutes in order to minimize the ammount of ë< 
information that would be lost in the event of a systen pro 


Forms for file names and passwords. File passwords 
names must be composed of 1 to 7 of the letters 4 to І 
о to 9, must begin with a letter, anê must not contaiz 
embedded blanks. File names should be distinct from aires ¿s 
for other files or workspaces. Use of the same name wi 
in an error message when an attempt is made to untie сле : 
created file. (For a direct access file, the error occurs + 
PCRPATE attempts to create the new file.) 


Range for file numbers, File numbers can be any nonnegative 
Integers not Greater than 7162-17. 


Range for record numbers. — File record numbers can be any 
nonnegative integers not greater than ~2+2417, 


FILE SECURTTY 


A file is owned by the user who created it. “he owner is 
allowed to alter the file in any desired manner, but the owner 
сап control access by other users through the following controls: 


1. The file category is ordinarily private. Private 
files cannot be accessed by other users unless their 
user numbers have been given explicit access permission 
by use of the KRONOS PERMIT command (see Chapter 12). 
Alternatively, the file can be assigned a category of 
semiprivate or public. Either of these categorics 
allows other users to access the file if they know the 
password. The CLIP command will reveal to another user 
the names of files that аге semiprivate, public, or 
that are private and have been explicitly made 
accessible to the other user. To make a file public or 
semiprivate, use the options PU or £ when the file is 
created, or use the KRONOS CHANGE command to change the 
category. When the [LIB function із used with a file 
name, the result shows when the file was created, when 
it was last changed, and when it was last accessed. In 
addition, for semiprivate and private files the system 
retains the number of accesses and the time of the last 
access for each user of the file. This information can 
be displayed by use of the KRONOS CATLIST command (see 
Chapter 12). 


2. The file can be given a password. Only users who 
know the password can use the file; however, the owner 
of the file is never required to provide the password, 
The password can be assigned when the file is created, 
or the password can be assigned or changed hy use of 
the KRONOS CHANGE command (see Chapter 12). 


3. The file mode can be used to control the type of 
operation another user can perform. For files created 
by APL (including workspaces) other users are 
ordinarily allowed to read the file (assuming the 
password and category do not exclude them) but are not 
allowed to alter or destroy the file, Other users can 
be given permission to alter the file by specifying the 
ZR option (for write) when the file is created. For 
private files, this mode has no significance because 
when other users are given explicit access permission 
via the KRONOS PERMIT command, the permitted access 
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mode for each user becomes that expressed in the PERMIT 
command. Рог semi-private files, the general access 
mode is applicable to most users of the file, but an 


overriding access mode can be specified for individual 
users by use of the PERMIT command. For example, most 
users might be allowed to read the file, while а few 
selected users night be allowed to alter it. The 
general mode allowed for other users can be changed 
after the file has been created by use of the KRONOS 
CHANGE command. Рог APLUM files the rode should be 
write or read-mocify, while for coded files it should 
be write or read. 


4. Files can be accessed by other users through locked 
functions which can provide extremely general contro! 
over the permitted operations. For example, the locked 
function can prohibit alteration of the first five 
records of the file, or, it can prohibit adding records 
that are not vectors of 4 integers. The success of 
locked functions ,as a security measure rests on 
preventing the usér from learning the file name, the 
user number, or the password, and preventing him from 
accessing the file directly, То assure this, the 
locked function should not call other functions (except 
those local to itself) lest someone substitute a 
subversive function having the same name. In 
particular, [FI should be used directly rather than 
using FTIR., (А subversive РТТЕ could print its 
arguments and thus reveal the file password). Also, С 
input should not be used while the file is tied, and 
the file should be untied prior to exit from the 
function. To ensure that the file will be untied, use 
ОТВАР to specify a trap line that will release the file 
prior to exit. 


Note that the file category, password, and mods are independent 
restrictions ол access by other users. Each of these further 
restricts the type of access permitted to other Unless 
different options are specified when the file is created or the 
controls are changed, the APLUM system selects private as the 
file category, assigns no password, and selects read or 
read-modify mode {depending on whether the file is coded or APLUM 
type, respectively) so that other users may only read the file. 


APLUM FILE OPERATIONS 


Sequential file operations. The file operations that ordinarily 
гейге a racord вылет can also be used without specifying tho 
record number. When this is done the record number used is the 
current file position (available in the result of PSTATUS). The 
file position can be reset using FPOS and is incremented by each 
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successful read, write, or deletion. Whena file is tied or 
created, the position is initially zero. Yor example: 


"XPAY'ETIE 5 (The file position is zero.) 

Z-PREAU 5 (Record D is read; the position becomes 1.) 
K FWRITE 5 (Record 1 is written) 

Y FWRITE 5 (Record 2 is written) 

M PWRITE $ (Record 3 is written) 


When a record number is provided for the operation, the file 
position will be set one greater than that number if the 
operation succeeds. 


File create: 'file-namo [:passwd] [/oprions)" FCREATE fnum 

The file create function can be used to create a file and specify 
options about the type of file, Wher the file is created, 
tied to the file number num. In addition to the name 
file, the left argument may include the password the file is to 
have. Examples of file creation follow: 


'PILSi! FOREATE ii (A file named FISEL with 11 
as its number.) 


"PILE2: SESAWE'FCREATE 2 {A file with SESAME as its 
password.) 


The list of options can include ary of the following separated by 
spaces: DA, С, WR, 9, Or PU (to specify direct access, coded, 
write mode, senmiprivate, Ог public). The option ЯМ is 
Appropriate for APLUM files, while НО is the corresponding option 
for coded files. These are discussed in other sections of this 
chapter. 


File write: array FWRITE fnum[,rnumj 
"The FWAITE function writes its left argument on the file having 
fnum as its number as the record having num as its record 
number. This will replace any existing record in that fiie 
previously having that record number. 


File read: result+PREAD fnun[,rnum] 

The FREAD function reads from the file having fnum as its file 
number that record having raum as its recor number. If that 
record does not exist, an empty numeric vector is returned, and 
the file status (see FSTATUS) will indicate that the last read 
attempt encountered a nonexistent record. 


File record delete: FRDEL fnual,rnum) 

The FADEL function deletes the record rnum from file fnum. If 
the record was absent already, nothing is done (except that the 
file positior changes) and no error results. 


Free record number: rnum=FFREE [num 
The PFREE function returns the first free (unused) record пипоег 
for file faum, This is a useful way to select the record number 
for a new record when the application does not requiro a 
particular ordering of the records. 


Pile positioning: FPOS fnuw,znum 
The function FP0S sets the position of the file identified by 
fnum to record number rnum. 


File status: result-FSTATUS fnums 

The flle status function returns various information about the 
Condition of files identified by file numbers in the right 
argument. If the argument is a vector, the result is a matrix 
having a row for each file number in the right argument. If the 
argument is a scalar, the result is a vector of information about 
the single file. The colunns of the result contain: 


Column Contents 
Largést record number currently in use 
or lif the file is empty. 


2 Current file position. 
3 File size in words. 

4 Unused space in words. 

5 Lost space in words. 

6 Space not used because of record sizes not 


being divisible by 64. (This space is called 
"tails" because it resides at the tail ends of 
Physical record units.) 


7 0 if APLUM type file, 1 if coded type 
file. 
8 0 if indirect access file type, 


1 if direct access file type. 


9 0 if last read attempt succeeded, 1 
if the record was absent. 


Note that only columns 7 and 8 are meaningful for coded files. 
All columns will be zero if the file is not tied. 


The largest record number does not take account of records 
that have been deleted. That is, tho largest record number is 
the largest number currently in use for records that actually 
exist. The largest record number is convenient to know when 
adding a new record to the file. Adding 1 to the largest record 
number gives а safe record number to use to append а new record. 


Print status: PSTATUS 

The ?STATUS function prints the information returned by FSTATUS 
PYUMS along with the file names, The information is giver in а 
descriptive format and is thus a convenient way to discover the 
status of all tied files if you do not remember the meanings of 
the columns in the result from PSTATUS. The following example 
illustrates the format used. 


PSTATUS 
NAHE NUMBER LAST R POS UNUSED LOST PAILS 
COMTIME 19 8 ° E о 397 
LIB 2 í i5 в 5 че DA 
+А123%56 SYSGEN 45 CORED FILE 
REPWAH? 1 n о £0384 2496 77и, 3233 DA 
ile names: result«FWAMES 
The РПАМЕ5 function returns a matrix of names (and user numbers) 


of files currently tied. ‘The number of columns in the matrix is 
always 16. For example, 


ENANES 
SAMPLEL 
ALGEBRA 

*A123656 PILEL 


File numbers: result-FWUMS 

The FNUMS function returns a vector of numbers in use for tied 
files. The order is the same as the order of file names in the 
result from FNAMES. 


File untie: FUNTIE fnums 

The РОИТТЕ function unties all files for which their file numbers 
appear ín the vector or scalar right argument. This produces a 
permanent stored copy of each file. The new permanent copy will 
replace any previously existing file having the same name, unless 
the active file vas newly created. To untie a newly created file 
when the вале name is already in use for another stored file, 
first use IROP to remove the old file. If апу of the files 
specified in the argument is not tied, nothing is done and an 
error message results, То untie all tied files, use PUNTIE 
PHUMS. 


File return: PRETURW fnums 

The FRETURW function behaves as PUNTIG for direct access files 
and behaves as PERASE for indirect access files. This frees the 
number of a currently tied file for other uses with a minimal 
impact on stored files. The use of this function is recommended 
for cleaning up any files that may have been accidentally left 
tied. File numbers in the argument that are not in use for tied 
files are ignored. 


FERSASE fnums 

ASE function crases the active copy of the file but leaves 
stored copy of the file. (See the Section on direct access 
г exceptions.) To remove a stored copy, use {2ЛОР. 


File tie: 'file-name [:passwd) [/options]! FTIE fnum 

he F7/E function gives the number £num to the previously stored 
file having the indicated name. If no previously stored file 
having that name is found, an error message is given and no file 
tie results. If a user number is given, the stored file is 
sought under that user number rather than the one used when 
signing on to the system, The password need be given only if a 
another user number was provided and a password was given to the 
file when it was created using PCNZATE. Examples using РТІЕ 
follow: 


‘PILES! PITIE 7 (A user ties ons of his own files.) 
40901238 RILEG'TTIE 8 (A user ties a file belonging 
to another user.) 


144123856 PILE) :SESAME' FOIE 9 


Note that the options 04 and C (for direct access or coded files) 
must not be provided to the FTIE function, These options are 
chosen wher the file is created ané can be altered only by making 
a copy of the file. If the file number or file name is in use 
for another tied file, an crror message results. The list of 
options can include either of the options Ri ог АМ. These 
options are discussed in later sections. 


SPECIAL CONSIDERATIONS FOR CODED FILES 


Coded files are the standard type of file on the KRONOS 
system for information interchange between programs, сага 
readers, printers, and so forth. ^ APLUM can access any coded 
files provided they contain lines no longer than 1280 characters. 
Coded files are essentially intended for sequential access; 
replacement of records, except at the ena, is not practical. 
instead, such changes would ordinarily be made by copying the 
file and making the changes as the new file is produced. 


Coded files consist of lines (essentially vectors of 
characters) which can be separated into groups by end of record 
marks. These groups can in turn be separated by end of file 
marks. At the end of the file is an end of information mark. 
The characters in a line of a coded file are restricted to 63 
characters. The 256 APLUM characters are translated into these 
63 chafacters as shown in Appendix C. Briefly, the letters А to 
Z become A to Z, all symbols with approximate equivalents for an 
ASCII printer are translated into those equivalents, and all 
others become 8. When translating from the KRONOS character set 
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symbols are represented by equivalents, 
as (the symbol used for illegal 


The functions FTIE, FUN?IE, and FRETURN have essentially the 
Same meanings for coded files as for APLUM files. llowever, 
Special functions must be used for reading, writing, and 
repositicning coded files. 


Creating а coded file. А coded file сап be created using 
PCREATE by including С as an additional parameter. For exazplu, 


"РЕІЙТ :XXY/C'FOREATE 3 


Coded read: resule+CPREAD fnum 

The result returned by CFREAD is a character vector containing 
the next line from the file, or if an end of record, end of file. 
Or end of information was encountered, the result ‘is the scalar 
integer 1, 2, or 3, respectively. ‘The file position changes 
after each read so that the next read will give the next line of 
the file. Тһе FREAD function cannot be used in place of C?READ 
with a coded file. 


Coded write: array CFWRITE {пиш 

The Teft argument to СЕНРТТЕ is written at the current position 
of the file, The left argument must be a character vector, 
Scalar (which is treated as a one-element vector), or matrix, or 
а acalar or vector containing the integers 1, 2, or 3. A 
Character scalar or vector produces one line in the file, whereas 
à matrix produces one line for each row of the Matrix, Trailing 
blanks in a line are removed. The integers l or 2 produce an end 
Of record mark or end of file mark, respectively. A vector of 
integers can be used to produce a series of these marks, The 
file position is altered after each write 80 that subsequent 
writes will add information after that Produced by the present 
ono. a PXthing written to the file is automatically followed by 
an end of information mark. This has the effect cf truncating 
fhe file if the write was not performed at the end of the file. 
The function PYRITE cannot be used for a coded file in place of 
CFWRITE. 


Coded file positioning: intesezs CFPOS Гошт 

The function СРРО5 repositions the file according to integers in 
the scalar ог vector left argument. The first element in the 
left argument indicates the action to be taken, and the optional 
second element may contain a repetition count. 


Operation Value 
Rewind 


Skip record 
Skip file 
Skip to end 


wno 


The rewind operation positions the file at its beginning. The 
rewind and skip-to-end do not allow ese of a repetition count. 
For the skip record or sxip file operations, the repetition count 
may be negative to skip towards the beginning of the 
repetition court is given, à count of 1 is assunec. 
record operation counts end of filc marks as records. The 
skipping never goes past the end of information mark or the 
beginning of the file, even if che repetition count has not been 
satisfied. 


Batch job submission: {72 fnan, type 

The coded file fnum is submitted as a batch job. The type may be 
O if batch output produced by the job should be discardec, or 1 
if it should be printed or punched at the central batch site. 
The file must be a properly constructed job file (see KRONOS 2.1 
Reference Manual]. In particular, the first two lines must be а 
job card and account card. The file must not be direct access 
type. 1f the operation is successful, the active file vanishes 
as if PERASE had been used. ‘The result returned is the job пале 
assigned to the job. This name can be used with KRONOS ENQUIRE 
command (see Chapter 12) to determine whether the job has 
completed, Note that the number of concurrently executing 
deferred batch jobs allowed for a given user number is controlled 
by the system. The number can be determined by use of the LIMI7S 
control card (see Chapter 12). 


SPECIAL CONSIDERATIONS FOR DIRECT ACCESS FILES 


A direct access file differs from an indirect access file ir 
that all operations interact with the permanent file itself, not 
with an active copy. This has both advantages and disadvantages. 
One advantage is that a copy of the entire file need not be made 
by the system wher. the file is tied. One disadvantage is that a 
program can stop executing due to a system problem in the middle 
of a serios of file writes, and the stored file can end up with 
contradictory information. Another disadvantage of direct 
access files is that write operations takea little longer 
(because the APLUM system does less buffering of information due 
to the risk of a system problem freezing the file in a temporary 
state). 


To create a direct access file, include the parameter DA іг 
the left argument to FCREA?Z. A direct access file may also be a 
coded file if desired--chese two options can be chosen 
independently. The following are examples of direct access file 
creation: 


'"PILEX/DA! FOREATE ч 
"PILEY: Y72794 $ ER PCREATE 5 
"FILER/C DA* РСВЕАТЕ 


All operations with direct access files take the same form 
as for indirect access files, but because of the differences 


between the two file types the file tie, untie, and file crase 
operations behave differently: A file tie to a direct access 
file does not make a copy of the file. An untie does not create 
the permanent copy, it merely releases the file number for use 
with other files and releases the file itself for access by other 
users. An erase removes both the active and stored copy of the 
file because they are the same thing. In addition, )CLEAR or a 
telephone disconnect cause an automatic FUJTIP of a direct access 
file (thus leaving a stored file) whereas an indirect access file 
would be erased. 


If an telephone disconnect occurs, the file remains tied for 
10 minutes, The operations that were in progress сап be 
continued by use of the XRONOS RECOVER command (Chapter 12). 
However, an attempt to sign on without using the RECOVER command 
will leave the file tied until the 10 minute period is over, 
possibly causing an error message indicating the file is busy. 


SYNCHRONIZED FILE OPERATIONS 


At present, it is not very practical for two users to update 
a single file at the same time. With an indirect access file the 
two users are actually updating separate copies of the same file, 
and whichever user unties the file last will create a stored file 
with his updates, but will replace any stored file just produced 
by the other user. The KRONOS operating system does not allow 
two users to be tied to the sane direct access file in write mode 
at the same time, so no conflicts can occur, but an error occurs 
if а second user attempts to tie the file. However, users can 
tie a direct access file in read mode {which allows other users 
to read the file at the same time) or read-modify mede (which 
means the user desires only to read the file but has no objection 
to another user writing to the file at the same time]. To tie a 
file in read mode or in read-modify mode, include PD or AM (but 
not both) in the left argument to the FTI? function. For 
example, 


'PILS1/RD'FTIZ 9 (Read mode.) 

*PILE2: SECURE/RH' FTIS 10 (Read-modify nodo.) 
These modes have meaning only “or direct access files and must 
not be used unless the file is direct access. Read mode can be 
used for АРЫМ or coded files while read-modify mode is allowed 
only for APLUM files. 
FILE EFFICIENCY 

Although many users need not concern themselves with the 


information presented here on file efficiency, users of very 
large files will find this information important. Use of a few 


fairly simple techniques can result in improved speed and reduced 
storage requirements. 


First of all, each APLUM file has an initial size of 64 
words used for a table of available space. їп addition, one word 
is required for cach record number up to the last reccrd number 
in use. This space is allocated in multiples of 64 words. These 
two factors combine to make it inefficient to store many files 
with only a few records in each rather than one file with many 
records, Also, it is inefficient to leave large gaps between 
record numbers as the unused numbers require an average of one 
word each. 


Indirect access files grow in multiples of 64 words, but 
direct access files grow in multiples of a logical track (usually 
several thousand words, depending on the storage device used). 
There is consequently a considerable space advantage to using 
indirect access files for files smaller than several thousand 
words. 


Pile records require 2 words more than they requiro in the 
workspace, and the space for records is allocated in multiples of 
64 words. However, large records of character or logical type 
require only about half as much space in the file, Because 
records require multiples of 64 words, there is some saving in 
space if many little arrays can be packed together and written as 
a single record. 


When records are erased or replaced by records of a 
different size, the APL system keeps track of any unused gaps in 
the file where records can be placed in the future. The total 
amount of this space in words is in column 4 of the result 
returned by the PSTATUS function. It may happen that the number 
of gaps exceeds the size of the table, in which case the saallest 
gap is removed from the table. This results in a certain amount 
of space becoming unusable, and the total amount of this lost 
space is in column 5 of the result returned by the status 
function. Lost space can also result in a direct access file if 
a telephone disconnect or system problem prevents the file from 
being untied  (DTM'SYSTZM', DTM'ABOPT', and DTM'OFF' untie files 
properly}, and if the RZCOVER command is not or сап not be used. 
All lost and unused space can be recovered by copying all records 
toa new file, last record first, and using the new file as a 
replacement for the old one, Because cach record occupies a 
maltiple of 64 words, some space is generally left unused, This 
space is returned in column 6 of the result from PSTATUS. 


Details of the space required for coded files саг be found 
in the KRONOS 2.1 Reference Manual. Coded files have a specd 
advantage over APLUM files when the information is accessed 
sequentially, the records are small, and the limitations of the 
63 character set are not restrictive. 
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INTEGRITY OF DIRECT ACCESS APLUM FILES 


File integrity refers to the ability of a file to retain 
internal consistency. Some file access methods render a file 
practically useless if a program operating оп the file does not 
complete properly (duc to a flaw in the program or a systen 
problem). Every effort has been made in the design of the APLUM 
file system to minimize the chance of such damage. 


All alterations to an APLUM file are performed immediately 
and thus occur in exactly the order requested. When multiple 
files are being updated, one file will not be several 
transactions ahead of another. A checksum is computed for each 
file record зо that if the storage device corrupts the 
information and is unable to detect the error, the error will 
still be detected by the APLUM system. A system halt, program 
halt, or telephone disconnect will leave the file in a 
satisfactory state except that in the rare event of a system halt 
requiring a level zero deadstart within a minute of extending a 
direct access file, there is some chance of damage to newly 
created or replaced records. 


File damage will cause an error message to be printed at the 
time it is detected, Тһе damage will usually affect only one 
record of the file. — If the file cannot be reconstructed, 
installation personnel can assist with restoring the file to its 
state the last time files were dumped to magnetic tape. 


Note that a telephone disconnect or system problem that 
results in failure to untie the file may cause the information on 
file space utilization (unused space, lost space, and tails) to 
be incorrect. This does not hinder utilization of the file and 
can be corrected by copying the file. 


PILE EXAMPLES 


The following sample functions taken from the workspace 
FILES? under user number APZ: illustrate simple file operations. 
The first function, FCOPY, can be used to copy an APLUM file. 
Such a copy might be made to convert the file from indirect 
access to direct access form or to compact the file by minimizing 
unused space. The left argument should be the character argument 
required to tie the old file, and the right argument should be 
the character argument required to create the new file, Note 
that the first line illustrates a simple way to select a file 
number that is not already in use. 


22002707 
94 ECOPY 5;P 


[y A T. 

[2] B РСРЕАТЕ 4+1+1 

[31 K-(PSTATUZ I)(12 a СЕР LARCEST RECORD NUMBER 
[s] Lire(X«0)/L3 

[5] — PePREAD I,K a READ RECORD К FROM PILE 1 
[6] *(PSTATUS /)(91/L2 а IF ABSENT RECORD 
t?) P PHRITE J,K я WRITE RECORD K TO FILE 7 
[8] 12 1 

[9] ча 

[io] :FUNTIE 1,5 в UNTIE BOTH FILES 

[111 'OPY COMPLETE* 


The next function is useful for listing a coded file. The 
right argument may be the name of a stored file or the number of 
an active file. If a name is given, the file is tied, listed, 
then untied. If a number is provided, the file is listed 
beginning at its current position and is left tied, 


vCLISTLOJV 
VCLIST B;kiL 


[1] — -(0-0V0pX-B)/L1 а IF PILE ALREADY TIED 


12) B FTIE K-14[ /0, FWUMS 
[3]  E1:LeCPREAD К 

[4]  +(0=09РЕ)/Б2 а SCALAR INDICATES SPECIAL MARK 
[51 

[61 

17] E3426 L-1 

[al -END OF RECORD-' 

Ca) 

[10]  '-END OF FILE-! 

[11] Li 


[12j  '-END ОР INFORMATION-" 
[13] — FUNTIB(0«OoB)/K 
7 


The next two functions are useful when a file is too large 
to list at a terminal but tt is necessary to learn the general 
structure of the file. The function FMAP prints the structure of 
an APLUM file, and the function СМАР prints the structure of a 
coded file. Both functions allow a character argument or а 
numeric argument in the same manner as CLIST. If the file is 
already tied (Zor numeric arguments) the mapping begins at the 
current file position. MAP prints record numbers and the types 
(С or И for character or numeric) and shapes of recorés that 
exist, or ASSENT for absent records, CMAP prints the number of 
lines in records and prints POR, БОР, or EOI when an end of 
record, end of file, or end of information is encountered. 
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yeaa P[Cly 

УРМАР B;K;P 

+(920\00K+8)/L1 в IF 5 IS NUMERIC 

B FTIE Relf /0,FNUMS 

51:+( 1=1^Р5ТАТИЯ K)/L2 a IF PILE ПОТ EMPTY 
YRO RECORDS" 

+0 

L2:'NUMBER, TYPE, DIMENSIONS? 

Laie(«/24FSTATUS K)/LS в IF FINISHED 
Р-ЕВЕАР K 

2(FSTATUS K)[9]/Lu m IF READ FAILED 
1e(FSTATUS X)[2]:0 2 OV'CH'[1«020V0pP];pP 
>13 

L4:71+(PSTATUS К)С2];' ABSENT" 

+23 

£5: FUNPIE( O#O\OpHI/K 

H 


voMAPLOV 
SCMAP В:К: РУС 
»(0z0V0pKe3)/L1 в IF B 
B FTIE K-iW[/0,FWUMS 
+0 

(0sppPeCFREAD L)/L3 
Ceca 

+? 
19:4 (С=0)/Еч 

LINE’, (C#1)/*S! 
:'EOT,IRPI' CPI 
*(P<3)/Li 
FUNTIE(O#0\0pB)/K 
я 


NUMERIC 


Chapter 10. APL Public Libraries 


The standard APLUM release includes the following workspaces 


stored under th 


APLNEWS 


BENS 


FILESYS 


PILES? 


PLOTPNS 


CATALOG 


STPI, STP2 


To learn how to use any of these workspaces, type а cor 


the form NLOAD' 


@ user number APLl: 


News about the changes in the APLUM system as well 
as a list of reported bugs and requests for system 
changes. 


Workspace utility functions. Includes functions 
SHORT, LONG, and SHORTSAVE for saving a workspace 
without 0Р7, OSY, &, B, 4, and т. 


File system functions. 


Contains functions from ZILESYS for primitive file 
operations as well as additional functions fer 
more elaborate file operations. 


Punction to produce an X-Y plot of multiple sets 
of data on a standard terminal. 


A guide to workspaces in the APL public libraries. 


‚ $TP3, STP4, STPS, SIPS 

А collection of | mathematical and statistical 
programs developed by К. W. Smillie of the 
University of Alberta, Primary documentation is 


in S7Pi. Capabilities include: descriptive 
Statistics, regression and correlation analysis, 
analysis of variance, — linear programning, and 


critical path. 


ара of 


*APL1 CATALOG" and then type SESCEIBE. 
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APL PROGRAM LIBRARY STANDARDS 


£ is suggested that installations reserve the user numbers 
APLI to AP: for APL public libraries. Although these vser 
numbers need not be defined in the system, they should not he 
used for other purposes. It is suggested that programs placed in 
these public libraries be of fairly general interest so that 
users will find it rewarding to browse through the various 
workspaces. Workspaces of interest only to a specialized group 
or course should be stored elsewhere. 


Programs placed in the public libraries should be well 
documented. The available documentation nay be entirely in the 
workspace or partly in the workspace and partly in a manual. In 
any case, the documentation should be readily available. тһе 
advantage of having the documentation in the workspace is chat it 
will be immediately accessible. Тһе disadvantages are that the 
documentation is slow to print and therefore tedious to read, and 
the format of the documentation is constrained by the APL 
character set. Generally, the amount of documentation determines 
whether it is practical to put the docunentation іп the 
workspace. 

Documentation in the workspace should consist of functions 
ог variables that describe the workspace, Тһе documentation 
should be able to be printed with a standard АРІ. terminal and 
should print within a standard 65 column ‘page width, The 
following documentation variables or functions are suggested. 
Typing the name of the function or variable should cause the 
information to be printed. 


ABSTRACT. Should contain a brief description of the 
contents of the workspace. 


DESCRIBE. This should give the user further details 
than that provided in the ABSTRACT. “his should print 
the names of all functions intended for the user to use 
as modules along with a short description and names of 


related НОУ functions (see below). If groups are 
defined in the workspace, describe them and their 
purposes, 


HOW functions. I£ a function has the name NAHE, 
detailed documentation of that function should have the 
name ИДМЕЯОМ. There is no point in giving a 
line-by-line description of the function. The APL 
program is already an excellent description of the 
Separate steps. The 40 function should tell what the 
function does and how to use it es a module. In some 
cases it should outline major steps in the processing 
and describe the method used. References might be 
appropriate. Special limitations of the function 
should be discussed. 


© 
ü 
EI 


SOURCE.  Shoul give the author's папе, an inqui 
nare, and an inquiry address, — The date when the 
workspace was contributed should be included. 


HANSES. Changes should be documented by & function or 
variable having а name of the form CHANCESC92075 {50 
that che name includes the date of the changes). 


GSPD9C, The group (locked matrix of names) GR 
should include names of all documentation variables anc 
functions so that the usec can readily erase them to 
make more space available in the workspace or reduce 
disk storage charges. 


Even when nost of the documentation is in a separate manual, the 
following variables cr functions are required: ABSTRACT, SOURCE, 
0С, and DESCRIBE. 
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Chapter 11. Optimization of APL Programs 


This chapter discusses some of the techniques that сал be 
used to make APL progsams perform better and run with lower 
demands on computer resources. It may seem out of place to 
discuss efficiency in ап APL manual--after all, APL should free 
the user from being concerned with the nature of the particular 
computer being used--but the techniques discussed here may yield 
efficiency improvements as large as a factor of a hundred. То 
neglect discussing efficiency could leave many users with the 
mistaken impression that APL cannot perform well enough to be 
used for their problems, 


Often, the question of efficiency calls to mind, the 
fanatical programmer who constructs a progran he considers 
efficient but who in doing so produces a totally incomprehensible 
collection of operations. It should be remembered that for many 
programs the programming time is so great that the only kind of 
Efficiency worth considering is the sort that makes the program 
easy to understand, free of errors, and easy to change. 
Fortunately, a simple program is usually an efficient program. 
However, when improving the performance of the program does not 
coincide with simplifying it, the optimization should not be 
applied unless it is very important for the program to perform 
well. 


Ав а very blatent example of misguided optimization, 
consider the following statement: 


Ket, pero, f /LeiQegP 


This statement was probably contrived by someone who believed 
that the most efficient program was the one that required the 
smallest number of lines. The fact is, execution proceeds from 
one line to the next very rapidly compared to the zine required 
to perform the extra steps needed to fit the operations in one 
line, The following statenents are a more straightforward way to 
achieve the same results: 
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Kel 
Legs pR 
Р-0.0 


one way со estimate the relative time required for an expression 
One чау Sone the number of operations required. (?his method is 
Hilly valid when the number of elements in аксау is less than 
{heat 20.) For this method of estimation, specification is not 
Oented at all (it takes relatively little time). The one line 
CountÓn totals 6 operations while the three line version requires 
Saly 3 operations. The efficiency expert who wrote the one line 
ОУ ion devoted extra time to adding three operations, which 
version the tine required for execution. Тһе one line version is 
боше to understand, is more likely to contain errore, aná when 
Phanges are made, the rest of the line hinders revision. The one 
алей сүз thus a poor example of efficiency in all respects. 


At this point it must be stated that much of the information 
in tnis chapter is relevant only to this particular APL system. 
Nise, it may occur that something that is particularly slow now 
Alil become particularly fast in later versions of the system. 
ner versions of APL on other computers will often show quite 
Güfferent characteristics, In fact, according za Paul Berry, the 
popular belief that one line programs are пото efficient is based 
Pies system for which this is true. А version of APL on the IBM 
од а avtually requires considerable time to change from one line 
tothe next because only one line ar а tine is kept in main 
memory. Although very few present users of APL ever used that 
particular system, its influence persists. 


STORAGE REQUIREMENTS 


Although the APLUM system allows а workspace of up to about 
90,000 words (provided the user is validated to use that much 
main memory and the installation has that much), .equivalent to 
675,000 $8-bit bytes, there are practical reasons to keep а 
workspace smaller. The KRONOS operating system uses computer 
resources much more effectively when it runs programs requiring 
minimal amounts of central memory. Also, the "response time" for 
Jn interactive program to respond to а command requiring а 
trivial amount of processing increases somewhat with central 
memory requirements. 12 addition, minimizing storage 
Tequirements improves the chances that the sane program will be 
Eee to run under another version of APL or on а computer with 
less central memory. 


тһе vector OWA contains information about the memory 
currently in use for the APLUM interpreter and the active 
workspace. тһе field length is the amount of memory space 
worker iy in use. The APLUM system manages that MEDOIY space and 
СЕ Колу given time some cf the space may not be in use for 
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fuactions, variables, and other information 
system. Тһе APLUM system evaluates storage 
time to tine and resets its actual field le: 
current needs. Тһе user can set [44 to speci 
minimum field lengths to be used. Іпсгеа 
minimum field length generally reduces tne central р 
used by APLUM to reorganize its storage, buc 
previously, re&uces the operating 
General rule of thumb, leave the minimum field length at i-5 
зоида] value, and set the maximum field length Large enough to 
avoid MS PULL plus a little extra to prevent frequent storage 
reorganization. Incidentally, referencing the value of ina 
statement causes the APIUM system to reorganize its storage, so 
programs should not alter or read the value of [WA too often or 
performance will be degraded. 


Obvious techniques for minimizing storage requirements 
include using algorithms that minimize temporary storage, using 
local variables and local functions to assure automatic erasure 
of unneeded objects, and.using СЕХ to erase other functions that 
эге no longer needed. ПЕХ can also be used to erase variables, 
but respecification (e.g., 4+'!) is faster. Piles can be used to 
store functions and variables until they are required. [L040 can 
be used to load another workspace of functions and variables. 
Any variables that must be communicated from one workspace to the 
next сап be placeó in files--files remain tied when another 
workspace is loaded. Of course, any of these techniques can be 
overdone. Го not let the time spent performing these operations 
outweigh the time they save. 


The space in words required for an APL array А is 
2+ (ррА)+Г(н/ oA +2 


where D is the number of elements packed per word--1 for floating 
point values, 4 for characters, and 32 for logical. Clearly, 
here isan advantage to using the internal logical 
representaticn if the values are ones and zeros. The system does 
hot always use the logical representation when it could. For 
катр1е, the scalar constants land О are floating point, and 
1+0 is floating point. ever, the following functions always 
produce a logical result: AAS, AVB, A^B, AYB, А=В, A5, A48, 
Рев, A28, and дев. Also, the functions that restructure от 
iearrange their arguments always preserve the sane type of 
representation, so ро is floating point, while Noi 9 is logical 
(because vector constants consísting of ones and zeros are packed 
{в Jogicals). то assure that a result is logical, apply 1+ to 
it. 


Expressions like Ava+c+11c0 do not cause three copies of 
1103 to be produced. actually, only one copy is kept. However, 
Xübsequently altering an element of A, й, or С, (e.g. 209-9) 
will cause а separate copy to be made. Similarly, arguments zo 
Functions are not actually copied unless an attempt is made to 
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alter them using indexed specification, Unlike most other APL 
Systems, using function arguments rather than global variables 
incurs no storage penalty. 


Storage requiremenzs for programs are too complicated to 
discuss in detail. As a rule of thumb, unless you make a special 
Oftort to put а lot on each line, figure that ап average 
statement takes about 10 words of storage. The first time a 
statement is executed it is converted to an internal form for 
more efficient execution. In the internal form the function 
Almost always requires somewhat more space. The storage overhead 
per line of a function averages about 3.5 words for lines without 
labels and 4.5 words for lines with labels. 


та version 2.12 of APLUM, function definition mode and 
system commands are performed by functions written in APL. When 
a user types Jexpression Or Yexpression the system translates 
these into ÜSf'Jexpression' and DFD'Texpression', respective ly. 
The functions [SY and 0Р0 are stored in the so-called "clear" 
workspace. In addition, some of the mixed functions are written 
ЧОКА and take space in the "clear" workspace, | It пау be 
desirable to erase these if they аге not required. For exanple, 
anyone who has mastered the equivalent System functions can 
Mminate 051 from his workspaces. Similarly, after а werkspace 
Sds been developed, OD can often be eliminated without hindering 
has Df the programs in the workspace. To minimize disk Stozage 
Charges [РР and 02У can be erased before saving the workspace. 
Таке workspace У5РИб in library APLI there is а function named 
та ke that can he used to erase all of these functions, and there 
SHORT Snetion named LONG that will copy in all of the functions. 
IS rt system improvements will eliminate all of these functions 
from the clear workspace. 


тһе APL system keeps a "symbol table" in the workspace 
containing all names of functions, variables, and labels. Once а 
cota as been used (even if the use resulted in а VALUE ERROR) 
mame lyme remains in the symbol table. The space used by names 
that are no longer needed can be recovered by copying all objects 
Тє a truly clear workspace. The recommended procedure is: 


DLOAD '«APLO EMPTY? (A clear workspace.) 
ПЕКҮ+0 {Сору global objects.) 
(1 2 з w DwANSS 'OLDWS')UCOPY 'OLDWS' 
QSAVE 'NERWS* 


‘This procedure will also recover space in workspace areas other 
than the symbol table in some circumstances. 


Space can be conserved in the symbol table by using name 
consisting of a single symbol whenever possible., Space can also 
consi ве оо еа by using the same name in several functions for 
pe al variables or labels. А common convention is to, Чал the 
local Ja to Z for local variable names and usc Di, 22, and so 
forth for labels. 


CENTRAL PROCESSOR TIME 


for many programs the main optimization problem is to 
minimize central processor tine. First of ali, one of che 
Primary determinants of central processor time is | tne 
Bppropriatness of the algorithm used. _ The algorithm should be 
abP'obriate to the data to be processed and appropriate to АГ. 
Computer literature is filled with algorithms thar | are 
Cofficient" for other languages but which perform miserably in 
APL. Often а straightforward translation of а program from 
einer language gives a program that performs poorly because it 
fails te take advantage of the more powerful APL functions, 


For most operations in APL the time required for the 
operation can be separated into а per-element tine required to 
process each element of the arguments and result plus а seras 
Pine required for interpreter overhead, to check the arguments 
for’ “Sompatibility’ of dimensions, to compute the result 
dimensions, and allocate space for the result. The tine per 
element varies considerably with the complexity of the operation. 
fhe "sine function, for example, requires far more time per 
clement than addition. The time also depends some on the way the 
Siles are stored; operations defined only for logic values 
perform better if their arguments are internally represented as 
Pogical type, and arithmetic operations are faster for the 
floating point internal type. ‘The setup time varies far less 
from function to function than the time per element. 


For many functions the setup time is on the order of 25 
tines as great as the tine per element. This means that th 
tatu time’ is negligible when thousands of elements are Ко ре 
processed, but the setup time constitutes about 95 percent of the 
Pine when only one elemert is being processed, For most 
programs, the setup time limits speed more than the tine Pet 
Pioicat.! chus the first step to optimization is to minimize the 
еее operations to be performed. For example, if pX is used 
апу times in a function, it would be worthwhile to assign the 
may of pf to a variable (assignent requires negligible time]. 
Often a branch statement can be added to skip steps that are not 
required except in special cases. 


When the arrays used have a large number of elements, the 
operations should be chosen to minimize the nurber of elements 
processed, For example, if V is а vector of 5000 characters, 4 
few elements can be selected from V using ММУ (which might 
process about 5000 elements) or using yigt] “(which would 
process only а few elements). The second approach is much roze 
ей Similarly, rather than extending а vector by 
Patemating one element at a time, it might be preferable fe 
СЕЛА it with a large number of elements and then respecify the 
Clements one at a time using indexed specification. 
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jt is commonly believed that APL branching for looping is 
slow. Actually, looping is faizly fast by itself but is usually 
a siga that the program is performing operations one element at à 
ime пе amount af time required is mainly due to the number of 
Siifations being performed. Actually, looping is gopetipes а 
Opty efficient way to perform an operation, especially if the 
verve of iterations required for normal cases is small ané the 
Diternative requires more opexaticns than are used in the 1099, 


тһе evaluation of constants other than 1, 2, 71, 9, .5, and 
+ + takes about half ав much time as the setup time for 
functions. Some time car be saved by using variables to store 
Che values of commonly used constants other than the common 
constants just mentioned. 


On some APL systems central processor time can be saved by 
catensting output together and then printing it in а batch rather 
Chun as it is generated. However, on the АРЫМ system it is more 
Efeicient to print the output as it is produced. 


The following chart gives approximate timings for various 
operations. Be forewarned that these timings axe approximate and 
Will vary with the version of APIUM in use, the particular 
computer used, and the internal workspace configuration. Times 
Gre expressed in terms of 7, the time per element for addition. 


Time range Operations 


o tor Time per element for And, Ava, ané -8 for logical 
internal representation 


T to sx? Setup time per statement to be evaluated 
Time per element for most scalar and mixed 
functions 


эхТ to 25*7 Time per element [or complicated functions such as 

дов, AeB, AGE, and ALB] 

Time ^ required for ап unnecessary set of 
parentheses in a statement 

Time required to evaluate a constant other than 0, 
1, 2, .5, 3, and ' Ta 

Extra time per local variable for a function call 

+В 

А-В 


захр to 125»? Call to a user defined function with a few local 
variables 
Setup tine for primitive functions 


Chapter 12. KRONOS Features for APLUM Users 


This chapter discusses a few KRONOS commands of interest te 
users of APLUM. The discussions cover only the more important 
details. Further information can be found in the KRONOS 2.1 
Reference anual or in the KRONOS Time-sharing User's Manual. 
Most of the commands ‘discussed can be used as timesharing 
МОЗ паз or batch job control carás. However, they Cannot be 
Ceed while in APL, Use the commands before issuance of the APLUM 
Command, or use Птм'5ҮЗТЕМ' to leave APL to use these Como дэ. 
Note that none of these commands allow embedded spaces. 


HELLO 

The RELLO command allows you to sign on again with a 
different account number. 
BYE 

тре command BYE is the correct way to sign off the system 


when not in APL, This is equivalent to the APL command D>s*C; 
or IFF. 


RECOVER number 


che RECOVER command can be used to return to the state just 
before a disconnect or system malfunction occurred. | The use of 
This command prevents loss of the active workspace ог active 
files. The comand is allowed only when the systen prints 
RECOVER/SYSTEM at the end of the sign-on procedure. If you have 
already proceeded beyond that point ала wish to initiate 
fecovery, type HELLO to begin’ the sign-on procedure anew. The 
number you provide in the RECOVER command should be the terminal 
number that was printed after the previous sign on. (that is, 
the terminal runber in effect for the session that terninated 


abnormally.) After you type the RECOVER command, the system may 
print RECOVERY IMPOSSIBLE, which indicates thet the system 
РЕ сетов was too serious to allow recovery, that too much time 
has elapsed (recovery information is retained for ten minutes), 
you signed on with a different user number, oF that you gave an 
you signe" terminal number. When the RECOVER command is 
in coessful, the recovery information is destroyed and the System 
prints various information about the status at the time of 
disruption. Press the RETURN key to continue for type STOP to 
РОВ APL). The recovery is sometimes imperfect. Бопе 
SXtput may be lost, and the next input request may caves D 
question mark to be printed, and any special APL symbols used in 
Re input may Бе translated incorrectly. ро not perform the 
Tecovery on a different type of terminal from that in wen when 
Тасо Bisruption occurred or the APL system will translate input 
and output incorrectly for that terminal. 


LIMITS 


тһе LIMITS command causes validation limits for the account 
number currently in use to be printed. Any numbers in the output 
that are followed by a B are expressed in octal (base 8). The 
APL functions base-value and represent can be used to convert 
between octal and decimal. For example, 70000B can be converted 
to decimal using 8:7 0000, and 32768 can be converte? to octal 
using (508)732768. ‘The following are the limits that are 
important to APLUM users: 


т, = CPU time limit in 10's (octal) per session. Append a 
Zero to the right of the number to find the CPU time 
{init in octal seconds. In addition, there may be а 
ег time limit per session, This ocher tine limit 
per session can be overridden by using, the БЕТ 
Pommand or by using the T,number command after a *TIME 
ТЇмгТ* error occurs, If you have consumed your entire 
CPU time limit for the session, you can use the XRONOS 
HELLO command to get a new CPU time allotment, or hang 
up, sign on again, and use the KRONOS RECOVER conmand. 


см = Maximum central memory field length. Append cwo zeros 
to the right of the number to find the central memory 
limit in octal words, Нобе that а moze stringent 
restriction can be imposed on all timesharing users by 
the computer operator, This second restriction may 
vary according to the time of day. 


DB 


n 


The number of jobs allowed for the given user. The 
ZSUBMi? function (see Chapter 9) is not allowed to 
Comit additional jobs if the total number of jobs for 
That account number already equals or exceeds this 
parameter. The count of jobs includes the progran 
Bttempting to use the CSUBMIT function. 
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FC = Maximum number of stored indireez access files allowed. 


Total storage in PRU's allowed for all stored indirect 
access iles. (Опе PRU is 64 words or 640 six-bit 
bytes-) 


FS = Maximum size in PRU's allowed for individual stored 
atest access files. (One PRU is 63 words ог 640 
six-bit bytes.) 


Hi = Access word. If the last digit is 4 or greater, the 
user is allowed to create direct access files. 


the following limits are not in effect for version 2.1.1 of the 
XRONOS operating system but may be in effect in later versions: 


WP = Number of local files allowed. This includes active 
APLUM files and coded files. Allow one extra file when 
Saving or loading a workspace. 


WS = Maximum mmber of mass storage tracks allowed for 
files, including active copies of indirect access 
files! One track may be anywhere from 1024 words to 
54,784 words depending on the storage device used. 
Contact installation personnel for details, 


In some cases SYSTEM may be printed as one of the above limits, 
which indicates that there is no limitation on the individual 
account number, but there may be а general limitation on all 
timesharing users. Contact installation personnel to determine 
this limitation. 


SECTL, number 


Sets the CPU time limit to “number. This can be used before 
entering APLUM to prevent a *TIME LIMIT* error from occurring. 
The number should be the desired tine limit in octal. In order 
to be meaningful, the time limit should be at least 10 {octal} 
and the last digit should be a zero. The time limit must not be 
set to more than the remaining allowance for the session. (You 
fan use “he HELLO command to start а new session and get a fresh 
allotment of CPU time.) 


T,aumber 


mhis command is meaningful only immediately after the system 
has printed “TIME LIMIT*. The number has the same significance 
has grining SETTL command, If you type anything other than 
Semper, a forced exit fron APL will occur and the active 
Gerkspaco will be lost. f you have used up the entire CPJ time 
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allotment for the session, hang up the phone ang then sign on 
Ggain and use the RECOVER command. 


DISPOSE 


The DISPOSE command is used to send a coded file to a batch 
printer. Note that the first character оп each line in the file 
Should be a printer carriage control symbol. A blank is usually 
А а 1 can be used to skip to the next page, ох а 0 can be 
used’ to skip а line before printing. Numerous other opzions 
Bede (see KRONOS 2,1 Reference Manual). | The following steps 
CTE po used to print a file at the central batch site: 


BATCH 
GET, filename 
DISPOSE (Fš Jename=PR/BC= account) 


where filename is the name of an indirect access coded file and 
account is your account number, If the coded file does not 
include carriage control characters in the first column, the 
following procedure Should be used instead: 


BATCH 

GET, filename . 

RETURN, TEMP 

COPYSDF ,filenanc, TEMP 
DISPOSE (TEMP-PR/BCe account) 


CHANGE 


ghe CHANGE command сап be used to change the папе of a file 
(which includes Workspaces), its passwords сачадо у or access 
(mich Permitted to other users. The following examples show 
simple forms of the command. 


CHANGE,newnamesoldname 
Changes the name from oldname to newname. 


CHANGE, #13 епате/СТесаседсгу 
Changes the category. The category specified may be P for 
private, for semiprivate, or PU fox public. 


CHANGE, fi lensme/M rode 

Changes the mode. The mode specified may Pe 4 for read, W 
Chand е, MODIFY for modify, or RM for read-modi ty. (Other 
fOdew exist but are not of interest for AZUM users.) 


CHANGE, filename/PWspassword 
Sets the file password, The password May consist of 1 to 7 
letters or digits. 


ENQUIRE, J= jobname 


This command can be used to determine the status of а job 
submitted using the CSUBM!T function (discussed in Chapter 9}. 
If the response indicates the job is not in the system, this 
usually indicates that it has completed or is presently bei 
printed. 


PERMIT 


The PERMIT command can be used to give another user access 
to a private file or to specify the permitted access node for а 
particular user of а semiprivate file. Tho form of the command 
is: 


PERMIT, filename ,account=mode,account=mode, ..- 


qhe mode for each account number determines the type of access 
allowed, Meaningful modes for APLUM users are R for read, W for 
write, RM for read-modify, or MODIFY for modify. 


CATLIST 


The CATLIST command can be used to examine access 
information about an individual file. Тһе following examples 
show how ко find information not provided by the APL 0212 
function: 


CATLIST/LO=F ,FN=filename 
Similar to OLIB’filename’ but also gives the password and 
count of the number of accesses. 


CATLIST/LO=FP ,FNefilenane 

Gives access information for each user who accessed the 
specified private or semiprivate file. The information 
printed includes the number of accesses by each user, the 
access mode allowed for each user, and the date and time of 
the last access by each user. 
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Appendix А. Error Messages 


The following list describes the APL error messages and 
their meanings. It should be noted that most of these cause 
execution to halt (unless СТАР is used to intercept the error 
processing), but function definition mode prints its error 
messages and then may continue processing. 


00: I#TERRUPT 

This indicates that an interrupt has been received from а 
terminal or that the overstrike 8 has been entered as the first 
nonblank symbol for quote-quad input. 


01: IMPLICIT ERROR 
An implicit argument to a primitive function is not defined. 
The system variable Dc? is required for the functions 4-8, A>3, 


ASB, ABB, ASB, A*B, AcB, AiB, and 18. The variable 510 is 
required for indexing, the axis operator, ANB, 445, AB, 48, 78, 
and А?8. The variable ЦИЗГР rust be defined for DSAVE'', ORE ia 
required for 473 and ?8, and DPP is required for monadic 
format. ОМУ is requireà for Пся, Dez, OFX, ONC, Оид, OSTOP, 


DWRACE, LILOCK, QLTIME, DHAMES and 0С0РУ. 


02: SYNTAX ERPOR . 

Incorrectly formed statement. Check to be sure the 
statement has matched quotes, parentheses, and brackets. А 
common error is to forget to place an operation symbol between 
two variables when catenation is intended (в.9., (/ N)pQ instead 
of (#,#}p@). Other causes include failure to provide a right 
argument to a function, and use of a branch arrow other than at 
the left end of a statement. Check the state indicator to be 
sure a local variable or label is not obscuring a function having 
the same name. 


23: DOMAIN ERROR 

The argument is not in the domain of the function or is an 
improper value for a systen variable being specified. Тһе 
following are examples of ways that domain errors can arise: 
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13.5 (an integer is required), DIO-1" (the index origin must be 1 
13-59), trs (character arguments are net. allowed for many 
Operations, even if the argument is empty), OUpPe4s (printing 
GPecision must be between 1 and 15). When ст is not defined, 
pres is used as Dor in domain checks. ass (1.18719 would not 
Zero vowed because exact integers are required when DCT is zero. 


ou: LENGTH ERROR 
Lengths of the arguments to а function are incompatible, or 
the operation is not defined for arguments of that length. 


oS: VALUE ERROR 

aoe iable used in an expression has, not been assigned а 
value, а dyadic function has been used without a left argument, 
уар sult variable of a function that returns а result was not 
кло gned a value, or a function was used for which there is no 
asson definition. Check the state indicator to see if а local 
Curf ble has obscured a global variable ox function. 


06: RANK ERROR 

fhe ranks of the arguments are incompatible or the operation 
is not defined for an argument of that rank. Бог example: 1 1 1 
(not defined for vectors unless they have one element), A[1;2J 
ШЕ А їз а vector it has the wrong rank for she index applied), Ё 
(i5 Goo (not defined for ranks greater than 2). 


07: INDEX ERROR 

бек out of range. For example, if A із а three-element 
vector: Ala] in 1-огідіп, A(3] іп zere origin, or Ato} in 1 
Srigin. To find the current origin, display DIO. 


св: LIMIT ERROR 

НИИ "operation exceeds limitations of the computer or the 
APLUM system. Limit errors can result from: attempts to generate 
APT suit greater in magnitude than aboot 1322, attempts to 
Be t S line longer than 120 characters (in а function, 
Stments to the execute function, of entered as input), attempts 
to produce an array having а rank greater than 75, or an attempt 
52 Phroduce а result requiring more storage than the entire 
central memory of the computer. 


оз: LOCKED OBJECT 

Lotenpt to specify a Value for a locked variable (label or 
group). Locked variables can be Zedefirea only by erasing them 
Gnd then specifying them. 


10: WS FULL 

We aufficient space remains in the workspace for the 
operation. Erase unneeded functions anā variables to make more 
Space available, or reset Пил te allow a larger workspace. 
sacar, do not set (WA to а greater fleld length than you аге 
validated for or you might actually increase the chance of WS 
FULL (soe LIMITS in Chapter 12). If there, 55 insufficient room 
EVLE (ue uting system commands, fry using system fonctions 
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instead. I£ that fails, try using specification to reduce th 
space required for larger variables (e.g. i«!'). Some space са 
Usually Be reclaimed by cxecuting a niladic branch (e.g., =). If 
more than one suspensi is on the stato indicator, ese а ni adio 
branch for each suspension. 


12: DEFN SRROR 

Incorrect request in function definition mode. Hay result 
from providing header information other than the function name 
when reopening the function, use of a function name already in 
Wse for another global function ox variable, or an illegal 
display or line editing request. ^ Another cause is az attempt to 
close "definition of a function having an incorrectly formed 
header or duplication of names used in the header or as labels. 


it: PHRASE МОТ FOUND 

The phrase specified was not found in the line where 16 was 
sought. Be sure to specify the correct line number. Display the 
line to determine the correct phrase. 


їч: SI DAMAGE 

Information on the state indicator has been lost due to 
changing a pendent function, by altering a function that is 
Suspended more than once, or by changing the number or relative 
order of local variables in the header or label variables for а 
Suspended function. This message is a warning--no corrective 
Action is required. ‘the pendent or suspended functions оп the 
State indicator that are affected by SI DAMAGE are indicated by 
enclosing brackets. “he affected functions cannot be continued, 
but they remain on the state indicator as long as other 
suspensions are above them. When the state indicator collapses 
Жо the affected suspension, the system automatically removes that 
suspension. 


15: ДАНЕ КОТ POURD 
no function or variable having that name exists. 


15: МАМЕ IN USE 
A function or variable already has that пале. 


38: MIXED FUNCTION 

А mixed function has been uscd where a dyadic scalar 
function is required as an argument to an operator. For example: 
д+. 10, Аз. 18, O/B. 


19: UNDEFINED PUNCTION 
Ho such primitive fun 
monadic z function). 


tion exists, Por exanple: a8, «P [no 


10: operating system error message 

This message is а message from the KRONOS operating system 
and usually concerns sone sort of operation with a file or with à 
workspace. See the list of common errors under OPERATING SYSTEM 
ERROR MESSAGES below. 


Usually indicates that one xecord of the file has been 
damaged. If an attempt to tie the file causes this nessage, the 


entire file may have been damaged. Most installations 
periodically copy all files to tape, and files can be restored to 
their condition when che last сору was nade. Contact 
installation personnel for assistance. File damage may be 


reported erroneously when reading a direct access file in mW mode 


if repeated interference is encountered from another user writing 
the same record. 


22: WRONG TYPE PILE 

An attempt was made to use CFREAD, CPPOS, CSUBMIT, Or 
CFVRITP on an APLUM file, or an attempt was made to use PPZAD Or 
FWRITE on a coded file. Note that the KRONOS COPY commands do 
not preserve the type with a copy made from az APLUM file, This 
error also occurs if an attempt is made to alter a direct access 
file that was tied in read or read-modify mode, 


23: FILE TIE ERRON 

An attempt was made to use a file number or file name that 
was already in use, or an attempt was made to perform an 
operation (е.9., PREAD, PWRITS) that requires the file to ре 
tied. 


OPERATING SYSTEM ERROR MESSAGES 


20: filename BUSY 

The specified direct access file is tied in ar incompatible 
mode. This may be caused by a system problem or telephone 
disconnect, in which case the file will be released in 10 minutes 
ог can be accessed by using the KRONOS RECOVER command to resume 
the session that terminated abnormally. Occasionally a file will 
be left busy due to an operating system error and will remain 
busy until a level zero deadstart (usually done at the start of 
the day). An APLUM direct access file can usually be retrieved 
fron this condition Бу using ДИ mode to лаке a new copy of the 
file. 


20: filename ALREADY PERMABEUT 

A file having the indicated name already exists. This error 
may result if a workspace is being saved and a password, 
category, mode, file type (i.e., I4 ог 04), cr a name different 
trom DWSID was specified. This error can also occur when 
FCREATE attempts to create a direct access file having the seme 
nane as a file already in existence or when FUNTIE attempts to 
store a copy of an indirect access file that was created during 
the session. If the old file is no longer needed, use DDPOP to 
eliminate it; Otherwise, copf the new file to change its name. 


x$ 


20: filename 30? РОБ 
The file does nct exist under the specified user number, 
the user is not allowed to access the file, or the user dii not 


provide a correct password for a file requiring a password. 


29: ILLSCAL USER ACCESS 
The user is either not allowed to огсабо direct access files 
or is not allowed to create indirect access files. 


20: FILE TOO LONG 
The file is too large for tho limits associated with the 
account number, 


20: PP UTILITY ACTIVE 

The computer operations staff is using a permanent file 
utility program that prevents users from performing operations 
involving permanent files. ry the operation again. 


20: CATALOG OVERFLOW - SIZE 
The operation would cause the user's limit on total size of 
all indirect access files to be exceeded. 


20: CATALOG OVERFLOW - PILES 
The operation would exceed the limit on the number of files 
allowed for the account number. 


PARITY ERROR 
ADDRESS PRROP 

DEVICE STATUS ERR. 

8581 PUNCTION REJ. 

DEVICE RESERVED 

DEVICE OT READY 

Any of these messages indicates a malfunction in the 
computer or a storage device. Try the operation again, aae if 
the problem persists, notify installation personnel. 


20: THACK LIMIT 

There is no space available on the device where the file 
resides. Пе sure you have not accidentally created а gigantic 
file. If you use very large files, you may need to make special 
arrangements with the installation personnel. 


ABNORMAL EXITS FROM APLUM 


PARAMETER ERRGR 
This error indicates the APLUM command was incorrect in form 
or that a parameter was specified incorrectly. 


TIME LTMIT 
A CPU *TIME LIMIT* occurred and the T,number command was not 
used to continue processing (see Chapter 12). 


А peripheral processing unit requested that the program be 
terminated. 


OPERATOR DROP 
The computer operator intervened and terminated the program. 


FILE LIMIT 
More active files were used than are allowed Ly the user's 
validation limits (see LIMITS in Chapter 12). 


SYSTEM ABORT 
The operating system terminated the program. This 
presumably indicates a defect in the operating system. 


APL SYSTEM ERROR (or EXCHANGE PACKAGE) 

This indicates а defect in the APLUM system or, a computer 
or operating system malfunction. Please report this error to 
installation personnel along with work that led to the problem 
and any further output from the  APLUM system. Unlike most error 
messages, this is not an indication of an error by the APL 
programmer. 


OTHER MESSAGES 


*DEL* 
This indicates that the input line was cancelled. 


*0VL* 
This indicates that the preceding input line was too long 
for the operating system. 


Appendix B. Output Format 


Character output is sent to a terminal unaltered except for 
character translation required for the particular type of 
terminal and omission of trailing blanks in rows of a matrix. 
This omission of trailing blanks in character output speeds the 
printing of the result from DCR, the printing of tables of 
rames, ard so forth. 


Womeric output 15 ordinarily shown in decimal form unless 
decimal form would not be sufficiently compact. When decimal 
form is used, up to DP? significant digits are shown, but 
trailing zeros beyond the decimal point are omitted, as is the 
decimal point itself if no digits follow, Numbers with a 
magritude less than l are shown with a zero before the decimal 
point (e.g., 0.025, 0.125). All numbers in a column have their 
decimal points aligned 


Exponential form is used if decimal form would require more 
than 3 zeros after the decimal point before the first significant 
digit, if aligning decima! points in the column would require 
more than 1.5:ПРР characters positions, or if more than DPP 
digits would appear to the left of the decimal point. If any 
amber in a column requires exponential format, the entire column 
is shown in exponential format with the decimal points and 
exponents aligned. All numbers in the column are shown with the 
sane number of digits in the mantissa. The number of mantissa 
digits is less than [РР according to how many trailing zeros 
would otherwise appear in all numbers in the column, If no 
muxbers in the column have digits beyond the decimal point, the 
decimal point is omitted. 


Numbers in adjacent columns are separated by at least one 
space. However, no more spaces than necessary are used. 


Appendix C, Character Sets and Terminals 


Many different types of terminals can be used with the APLUN 
system. In addition, card readers, printers, and files can be 
ied for input and output. The characters available on these 
various devices are shown in the table at the end of this 
Section. Many of these devices cannot print the full set of APL 
characters. APL characters are translated so as to print the 
Same whenever possible. In some cases characters having а 
Similar appearance аге substituted (c.g., " for апд € for e). 
În the table where two characters appear in the samo column, 
either character may be used for input, but all output uses the 
Second character, Note that the APLUM system assumes the same 
terminal type for input and output. Where there is a blank entry 
in the table, the "bad character symboli," [М7[2201,‹ is used. 
Note that the ГАР indices are for 0-origin, The first 128 
Alements of ГИР, when used in output, cause APLUM to issue the 
Corresponding ASCII code. However, further translation may occur 
Within the operating system for some types of terminals, 


TERMINAL CONTROLS 


Table C.l shows the characters used to cancel an input line, 
correct an input line, stop а program not requesting input 
(called an "interrupt" elsewhere in the text), and to stop а 
program requesting input. The two entries for halting a program 
Pequesting input are for quote-quad and quad input, respectively. 


TERMINAL TYPES 


From the point of view of the user, the three APL terminal 
types are almost identical except for the control functions show! 
in Tabie C.l. The only other difference is that the two ASCII 
terminals have the extra symbols (}Qb4 which are represented on 
Selectric terminals as the overstrikes fà к ++. “The Solectric 
terminals are distinguished from the others in that they are 


based on the IBM Selectric print mechanism. ‘These terminals are 
further divided into correspondence and EBCDIC terminals. The 
APLUM system allows either correspondence от EBCDIC terminals to 
be used, (The APLUM system does not need to distinguish between 
Eacbic and correspondence types because the operating system 
compensates for the differences). The Teletype Model 38 is an 
example of an ASCII-APL terminal, and the CDI 1030 is an example 
SF a blt-pairing terminal, All of these terminals аге shown in 
the character собе tables in the colum, showing APL symbols. 


Full-ASCII terminals are characterized by having upper and 
lower case letters. Because these terminals do not have all the 
APL symbols, many APL symbols must be represented by a dollar 
sign followed by two additicnal symbols. 


ASCII terminals include the Teletype Model 33 and Model 35. 
These terminals also require the usc of the dollar sign sequences 
to represent most APL symbols. 


the BATCH column is for ASCII line printers having 63 
printing characters. The B501 column is for the CDC 501 printer 
Phich differs in а few character positions from ASCII, The 501 
printer prints the KRONOS display code symbols. 


The file system translates coded file characters using an 
ASCII coding in the file, regardless of the terminal type 
Specified on the APLUM control card. If the 501 type printer is 
used instead of an ASCII printer, the APL symbols _l»'2e\~ will 
bore out as Zx+vatesz™ instead of #'' !a^?&V^ . 


TABLE C.l. TERMINAL CONTROLS 


CANCEL CORRECT STOP STOP *SIGN-ON 
INPUT INPUT PROGRAM INPUT CHARACTERS 
ASCII with ESC LINE-FEED BREAK por + ) RETURN 
APL print BACKSPACE 
Full ASCII BSC LINE-FEED BREAK — $G. or $60 — RETURN 
BACKSPACE RETURN 
ASCII ЕБС LINE-FEED BREAK $G. ог $60 RETURN 
CTRL-H RETURN 
Selectric APL АТТЫ АТТЫ ATTH до: + 
RETURN ЗАСКЗРАСЕ ATTN RETURN 


*Sign-on characters apply only at the University of Massachusetts 
installation. These characters should be the first characters 
typed after dialing the computer. Опе exception to the above is 
VET bit-pairing ASCIX-APL terminals require ORETURN аз the 
sign-on characters. 
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APL ASCII арг 


tay Symbol Syxbcl TTY33 BATCH B501 Coded 
Index (Overstrike) (Name) Symbol Printer Printer Files 
oj >» {шд | SNU БЕ ES 
1. a (son; $sH $5Н $5Н 
2 5 (STX) $st У5Т $5т 
3 Е (ETX) SET SET SET 
4 B (EOT) $EO SEC $ЕО 
* LÀ (ENQ) SEN SEN SEN 
6 x {ACK} $AK $AK SAK 
7 B (BEL) $BL ŞBL $3L 
8 a (BS) $BJ SBI $вл 
9 Li (нт) ŞHT SHT ŞHT 
10 z (LP) SLF SLF SLE 
11 Y (T) $vT SVT $vT 
12 B (FD) SFD $FD SFPD 
13 a (CR) $CR SCR $CR 
14 6 (so) $50 $50 $50 
15 $ (SI) $51 $81 $81 
16 B (DLE) $DE $DE $DE 
17 a (pc 1) $21 $01 $01 
18 2 (рс2) $02 $02 $р2 
19 E {рез} | $3 $23 503 
20 а toca) | spa 504 En 
21 xi (маҳ) | SNK Suk SNK 
22 s (SYN) $sy $sY 55ү 
23 B (ETB) $EB $ЕВ SEB 
24 5 (САМ) $СА $СА SCA 
25 А (им) | SEM SEM SEM 
26 8 (508) $5В $SB $858 
27 5 (esc) | 585 SES SES 
28 s (FS) SFS $FS SFS 
29 n (s) | ses $08 $65 
30 a (ms) | SRS SRS Б 
з1 H (05) | sus sus sus 
32 b: blank blank blank blank Dblar.x 
33 1 : $EX ! $ЕХ 1 SEX В 
34 
35 
36 $0 $ $00 spo spo s 
37 
38 | 
39 ' ' sor ' | sor’ | sor š 
40 ‹ ( ( ( ( 1: 
41 ) ) } ) ) d 
42 . * * * . |: 
43 + + + + + i- 
44 í r , , + ie 
45 - - - - - dc 


APL 
TAY Symbol 
Index (Overstrike}) 
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Symbol TTY33 
(Маге) Symbol Printer 


BATCH 


B591 


Printer 
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APL ASCII APL 


DAV Symbol Symbol TTY33 BATCH 3501 соёеа 
Index {Overstrike) (Name) Symbol Printer Printer Files 

91 t B son f зов | | sos r 

92 Ó \ $88 V | $05 SBS 

93 1 1 5св J зов у | св } 

94 

95 < a SUL SUL _ SUL 

96 = 
4 (42 a SAA SAA SRA A 
а (82 b $BB $BB E B 
€ (C c $cc scc gcc c 
р o) а $00 spp $DD 5 
È (E) e SEE SEE SEE Е 
Е (FL) f ЗЕЕ ЗЕЕ SEF F 
8 (с) 9 $66 $GG $66 с 
u (H. h gn SHH SHH н 
1 i $11 ў $11 1 
d & sud gar E 3 
Е х SKK $KK SKK x 
n 1 $LL SLL SLL L 
К n SMM SMM мм м 
a a SNW SUN SUN N 
о о $00 $00 $00 о 
Р р $PP SPP $РР Р 
@ q 500 $00 $90 © 
gi r $RR $RR $RR R 
5 s 588 ГЕН 555 s 
T t SIT STP STT т 
z ч sou 500 $00 ч 
¥ x sw $vv sw v 
E ` зин Зи Ed w 
z x $xx $xx $xx x. 
i y D ЗҮҮ $ҮҮ Y 
z 2 $22 szz RI z 
H 
1 
) 
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ASCII APL 

Symbol Symbol TTY33 BATCH В501 Coded 

(Overstrike) (Name) Symbol Printer Printer Files 
136 (K8) 
137 (кэ) 
138 (K10) 
139 (1) 
140 (12) 
141 (кіз) 
142 (14) 
143 (к15) 
144 (16) 
145 (K17) 
146 (к18) 
147 (к19) 
148 (K20) 
149 (K21) 
150 (k22) 
151 (K23) 
152 (к24) 
153 (к25) 
154 (к26} 
155 (27) 
156 (к28) 
157 (к29) 
158 (x30) 
159 (31) 
150 ^ (NO) 
161 у (81) 
162 к (a=) (н2) 
163 > (v~) (43) 
164 А (м4) 
165 = (х5) 
166 > (N6) 
167 4 (al) (N7) 
168 foD (NB) 
169 + (М9) 
170 р {810) 
171 + (N11) 
172 > (N12) 
173 я (n°) (N13) 
174 9 (7-) (N14) 
175 H (N15) 
176 Ë (N16) 
177 r (817) 
178 x (N18) 
179 H (019) 
(N20) 


APL ascit APL 
cay symbol Symbol ТТҮЗЗ BATCH Coded 
Index (Overstrike) (Hame) Symbol Printer Printer Files 
var. T en] sso e] sme: D 
182 а iN22)| spor от 

183 — [IN23)) $RK SRK 

184 нео (824) | тк SLK 

185 o (N25)] SCE $CI 

186 e (о) (к26)] srcej {1б е 
187 ө (o-) (м27)} SRU SRU 

188 $ (о!) (128) | ЗАТ SRT 

189 & (oN) (m29)| STP $TP 

190 $ (av) (N30)| $0м SDH 

191 à (а) (N31)| $00 $00 

192 \ (032) | 510 $10 

193 о (33) | $85 $RO 

194 n (N34)| SBV $BV 

195 T (N35)| SRP SRP 

196 т (ат) (w36) | 518 $1B 

197 < (N37) | SIN SIN 

198 a (N38) $10 $10 

193 а (139) | six Six 

200 v (N40) | SUN SUN 

201 Д (861) $NL SNL 

202 D (842) $95 $00 

203 m «aon (N43) $QP SQP 

204 X (7) (844) SBT SBT 

205 # (/-) (N45) 53м $sM 

206 (NAE) 

207 a (00 (N47) $xD $xb 

208 E (148) | 0м $0M 

209 a (ндә) | SAL SAL 

210 (N50) 

21) (051) 

212 (452) 

213 € (853) $EP SEP 

214 а (1°) (N54) SEV SEV 

215 ” (Te) (N55) $FM SFM 

216 E m (N56) $CN scu 

217 (837) 

218 (558) 

219 (N59) 

220 Е (94) (N60) sac $BC 

221 (861) 

222 (862) 

223 (163) 

g (оит) | (GO) $c. 55. 
g (20) (61) $00 sou 


° 


E 


ASCII 


APL 


ni 1 Symbol TTYJJ BATCH В501 Coded 
Iex joverstrike}) (Name) Symbol Printer Printer Files 
226 (G2) 
227 (G3) 
228 (64) 
229 (G5) 
230 (G6) 
231 (G7) 
232 (68) 
233 {69) 
234 (G10) 
135 (G11) 
236 (G12) 
237 (G13) 
238 (G14) 
239 (G15) 
240 (G16) 
241 (G17) 
242 {618} 
243 1619) 


Appendix D. APLUM Control Card 


The optional parameters on the APLUM timesharing command (or 
batch control card) allow specification of the type of terminal 
(or batch options) to be used, the workspace to be used (thus 
avoiding a subsequent LOAD command), and the constraints on the 
field length to be used. The general form for the control card 
ig: 

APLUM,optionevalue,optionevalua ... cptionvvalae 


Indicating terminal t When no terminal type is specified, 
APLUM assumes that an ASCII-APL terminal is being used if the job 
was entered from timosharing. If the job is a batch or remote 
batch job, APL assumes that 63 ASCII characters must be used for 
output (е.9., v becomes $10, р becomes $RO). Other terminal 
types can be specified as follows: 


TT«COR Correspondence (or EBCDIC) Selectric terminal 
(077-1). 


ДТЭТУРЕ Type-pairing terminals (077-2). 

ттезІт Bit pairing terminal (077=3). 

TUeASCAPL For ASCII-APL terminals (including Medel 33 
Teletype) equipped to print the APL character set. 
This type is normally assumed for timesharing 
users (D??29). 


T?-T7Y33 For Teletype Model 33 terminal or similar devices 
(Q#T=5). 


TI-ASCII For full ASCII terminals not equipped to print the 
APL character set (077=6). 


ТТ-ВАТСН For devices that support the 63 ASCII character 
set (UTT.7). Usually used for batch or remote 
batch ASCII printers. 

TT-3501 For batch 501 printer (гт). 


TT-TTY383 Teletype Model 38, keyboard arrangement 3 (02 


he 


At the University of Massachusetts (an? at a few other 
installations), the TT= option should not be specified for any 
terminals that print the APL character set because the operating 
system compensates for any differences from ASCII-APL, 


Indicati batch output options. The following options are 
intended primarily for batch users of APL. ТЕ the APLUM control 


Card does not specify output options, it is assumed that 
timesharing users do not wish these options and that batch users 
do want then. 


LO-EPS Апу or all of the options E, P, ог S may be 
specified. Any options not specified are not 
used. 

E Echo input. The APL lines read as input are also 
sent as output. 

P Prohibit prompt. Тһе normal APL input prompts (6 
spaces or 0: plus transparent mode control bytes, а 


lack of which may cause the input translation for 
terminals to be incorrect) are not sent to the 
output file. 


s Shift output. Causes a blank to be added to the 
front of each output line to prevent the first 
character from being used for printer carriage 
control. 


10-0 To select none of the E, P, or S options. 


Input and output file specification. ^ The input and output files 


normally used for APL are named INPUT and OUTPUT. For 
timesharing jobs this causes input to come from the terminal and 
output to be sent to the terminal, For batch jobs input 


ordinarily is from the card deck or CSUBMIT е, and output is 
to à line printer. Other KRONOS files can be used instead. APL 
translation of input and output is according to the TT option (or 
the default which depends on whether the job is batch type or 
timesharing type). 


I-file-name Causes input to be read from the named file. 


lsfile-name Causes cutput to go to the named file. 


D-2 


Led Ко APL output is produ (All output is 


discarded.) 


Initial workspace specification. £ no workspace is specified, a 
clear workspace is used. Some effort can be saved by specifying 
the initial workspace name on the APLUM control сага. 


WSswsname APL operations begin with a copy of the named 
workspace as the active workspace. 


Ul-uscr-nu»bez Used to specify the user number of the 
initial workspace. Required only if the user 
number of tke workspace differs from that 
used when signing on. 


PW: passwd If the workspace belongs to another user and 
has a password, the password must be provided 
in order to use it. 


Field length specification. If no field length is specified, the 
APLUM system chooses a minimum ficld length that depends on the 
current version of APLUM, and а maximum field length of 24576 
words (60000 octal). Thue field length is used for the APL 
system and the active workspace. The actual field length used 
varies dynamically. If storage requirements exceed the maximum 
field length, a №5 PULL message results. Note that specifying a 
field length greater than the user is validated to use or greater 
than the limit set by the computer operator may actually increase 
the chance of a #3 FULL error. То check user validation, use the 
LIMITS control card or the LIMITS command {see Chapter 12). 


MX-number Sets the maximus field length. The number is 
assumed tobe in decimal form unless followed 
immediately by 3, in which case it is interpreted 
as octal. The value is actually rounded up to a 
multiple of 64. 

MNenumber Sets the minimum number із 

assumed to be in ss followed 

immediately by E, in which case it is interpreted 

as octal. Тһе value is actually rounded up to a 

multiple of 64. 
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Appendix F. Numerical Limits and Precision 


mhe CYBER computers can represent nonzero numbers having 
magnitudes in the approximate range 4.278322 to 1.272 322. An 
Operation that would ordinarily produce a number smaller in 
magnitude than 1,275322 ‘actually produces zero. Most operations 
produce a LIMIT ERROR when the result would exceed 1: 072922 in 
Magnitude; however, simple operations such as addition and 
multiplication can produce += or which are printed as 
893 and -9.99£999. Using these infinite values for апу 
other operations will rosult in a LIMIT ERROR. 


Hunbers within this magnitude range are represented with аһ 
accuracy of about 14 decimal digits (more precisely, to within 1 
mart in 2«48). Тһе simple operations such аз addition, 
Pa eraetion, multiplication, and division can be expected to be 
Suptrece to within 1 part in 2«48 except when cancellation 
magnifies the errors. However, operations involving numbers that 
Еее: or powers of 2 give exact results unless the 
Signitudes differ greatly. For example, exact results атс given 
by: 5+4, .25-.125, 8-3. 


INDEX 


Abort 7-19 

Absent records 9-8,10 
Absolute value function 3-3 
ABSTRACT documentation 10-2,3 
Access information 12-5 


Access modes for files 9-6,7; 
12-4,5 
Accounting information (ПАЛ) 
7-6; 7-18 
Account number 
for files 9-10 
for signing on 0-2 
from DAI 7-18 
linits for 12-2,3 
Acoustic coupler 9-1 
Active workspace 7-7; D-3 


Addition function 3-2 

Additive inverse function 3-2 

ADDRESS ERROR А-5 

Cur 7-6; 7-18 

Alternating product 6-2 

Alternating sum 6-2 

AND function 3-3 

APLi public library 10-1; 11-4 

APLNEWS workspace 0-2; 10-1 

APL SYSTEM ERROR А-6 

APLUM control card 0-1,3 

APLUM files 9-1 

Arc sine, arc cosine, etc. 
3-5 

Arguments 
1-7; 


3-3; 


to functions 

2-4; 11-4 

ASCII-APL terminal type 0-1; 
C-2; 0-1 

ASCII characters 7-18 

ASCII terminal type 0-3; 
©-2,8; Del 

Assignment 0-3; 2-5,7; 
4-6 See also Indexed 
specification 

Atomic vector (ПАЙ) 
C-1,8 

ATTN key С-2 

DAV 7-18; С-1,8 


0-5; 


4-2; 


7-18; 


Axis operator 2-5; 5-5; 7-10; 
А-1 

BS01 terminal type C-2,8; D-2 

BACKSPACE key 0-3; C-2 

Base value function 5-18,15; 


7-7 
Batch job submission, see СБУВМТ 
Batch output options 0-1,3 
Batch printing of files 12-4 
BATCH terminal type C-2,8; 
Batch use of APLUM D-1,3 
Bit-pairing terminals C-2 
Blanks 2-1 
Branching 1-8 

and efficiency 11-6 

and execute 5-20 

and restarting execution 1-9 
BREAK key С-2 
BYE 12-1 


D-2 


Canceling output C-1,2 


Canonical representation (ПОР) 
7-10 

Carriage control 7-8,9; D-2 
Carriage return 

key 0-2 

suppression 2-10 
CATALOG OVERFLOW - FILES А-5 
CATALOG OVERPLOW - SIZE А-5 
CATALOG workspace 10-1 
Category of files 12-4 
Catenate function 
CATLIST command 12-5 
Ceíling function 3-2; 3-4 


Central Processor time 7-12,13; 
7-18; 11-5,6; 
CEPOS 9-12,13; А-4 
CFREAD 9-12; A-4 
СРУВІТБ 9-12; А-4 
CHANGE command 12-4 
CHANGES documentation 
Character constants 
Character sets C-1,8 


INDEX-1 


Character type 5-5 


Circular functions 3-3; 3-5 
\CEERR 7-6,7; 8-1; 9-14 
CLEAR HS 0-2 


Clear workspace 7-6,7 

CLIS? (to list coded filed) 

Closing function definition 
1-3,4 

CHAP 9-17,18 

Coded file read (сғағА2) 

Ccded files 9-1: 9-11; 
12-4 

Coded file write (CFWRITE) 

Cclumn coordinate 4-1 

Ccnbinations-of function 
3-5 

fommorts 2-1,2 

Comparison Tolerance IDcf) 
7-6; 7-8; А-1,2 

Composite functions 6-1,5 

Compress 5-10,11 

Connect tine 

Constants 

Context editing 1-5,6 

Control card for APLUM 0-1,3 

Conversion between number systems 
5-18 

CcoPY 7-14; 

COPY 8-3 

Correcting typing errors 0-3; 
C-1,2 

Correspondence terminal type C-2; 
Del 

Cosine function 

CPU time 7-12,13; 
12-2 

Qc? 7-10; А-1 

CRT terminals 

CSUBMIT 9-13; 

D-2 

35; 


9-17 


9-12 
3-15; 


9-12 
э-э; 


3-5; 


A-1 


3-3; 3-5 
7-18; 


11-5,6; 


7-9 
12-2: 
7 


oer 7-6; 


; A-1,2 


Deal function 5-7,8; 7-10; А-1 


Decimal format for output 5-22; 
B-1 

Decode function. See Base value 
function 

ФЕРИ ERRGR 1-3: 1-5; 1-10; 
А-3 

DEL* А-6 

Delay (000) 7-19 

Deleting function lines 2-4 

DESCRIBE function 10-2 


DEVICE ПОТ READY А-5 
DEVICE RESERVED A-S 
DEVICE STATUS ERROR A-5 


Diamoné symbol (line separator) 
1-6 

digits 

Digits. see ГРР 

)DIGIT8. see OPP 

Digits for output А-1; B- 

Dimensions of an array 4-1 

Direct access file 9-13,16; 

Direct access workspaces 7-7 

Disk storage space 11-4 

Displaying functions 1-4 

DISPOSE command 12-4 

Divide function 3-2 

Орр 7-19 

Documentation standards 10-2,3 

DOMAIN ERROR 6-2; 7-1; A-1,2 

Domino functions, See Matrix in- 
verse or Matrix divide 


2-2 


7-7 
12-3 


DROP 7-15 

)DROP 8-3 

Drop (primitive function) 5-13,)4 
Dyadic format 5-22,23 

Dyadic functions 2-4 

Dyadic save 7-13 

Dyadic transpose 5-17,18; А-1 
EBCDIC terminals С-1,2; 0-l 


Echo input option D-2 


Efficiency 
for APL programs 11-1,6 
for files 9-14,15 
Encode. s, Represent function 


End of information, file, or record 
9-11,13 

ENQUIRE command 12-5 

DENY 7-6; 7-10; А-1 

Environment control 7-6; 7-10; 
А-1 

Equals function 3-3; 3-5; А-1 

)NRASE 8-3 


Erasing direct access files 9-14 

Erasing functions and variables 
7-11; 8-3 

JERR 7-6; 7-16,17 

Error messages А-1,6 


Error processing 7715,18 

Error trapping 7-15,17 

FSC to cancel input 0-3; C-2 

ОЕХ 7-11; А-1 

Execution of functions 1-7,10 

Exception rules 5-1; 5-4,5 

EXCHANCE PACKAGE А-6 

Execute function 2-9; 3-20; 
7-16 

Expand fonction 5-11,12 


Exponential format for output 
5-22; Bel 


INDEX-2 


Exponential 
Exponential 
stants 
expression 
Expunge 


3-2; 3-4 
for con- 


2-7 
7-11; 


А-1 
Factorial function 3-3 
FCOPY 9-16,17 
FCREATS 9-8; 
Оғо 2-2: 7- 
FERASE 9-11; 
PFREE 9-9 
ОРІ 9-4,5; 
Field length 
D-3 
access information 12-5 
create 9-8; 9-12,13 
create 9-8; 9-12,13 
damage 9-1 A- 
erase 9-11; 9-14,15 
LIMIT А-6 
limits 9-3; 
names 7-15; 
numbers 9-6; 
passwords 9-5 
positioning 9-9; 
read 9-8 

File record delete :9-8 
File return 9-10 
PILES? workspace 9-16,18; 10-1 
File sizes 7-15; 9-9; 9-14,15 
File status 9-9,10 
FILESYS workspace 
10-1 

system 9-1,18 
tie 9-11; 9-13,14 
TIE ERROR А-4 
100 LONG А-5 
type 7-15 
File untie 9-10; 
File write 9-8 
Fix (ПК) 7-10,11 
Ploor function 3-2; 
FHAP 9-17,18 


3-12,13 
11-4 
9-14 ,15 


9-7 

7-19; 11-3; 12-2; 
File 
File 
File 
File 
File 
FILE 
File 
File 
File 
File 
File 
File 


12-2,3 
9-5; 
9-10 


9-10 


9-12,13 


9-1; 9-4; 
File 
File 
FILE 
PILE 
File 


9-14 


3-4 


PNAMES 9-10 
JPNS 8-4 
FNUNS 9-10 


Format for output B-l 
Format functions 5-21,23 


FRDEL 9-8 

FREAD 9-8; А-4 

Free record number 9-9 
PRETURR 9-10 

FSTATUS 9-10 

FTIE 9-11; 9-13,14 


Pull ASCII terminals 
Function classifications 


C-2,8 
2-3,4 


Function definition mode 1-1; 
1-10; 2-2; 7-7: 11-4 

Function execution 1-7,10 

Function header 1-1; 1-3,4; 
1-8,9 

Function names 1-1 

6681 FUNCTION ВЕЈЕСТ A-5 


Functions, user-defined 1-1,10 
listing names of 7-11; 8-4 

FUNTIE 9-10; 9-14 

Fuzz. See CCT 

EWRITE 9-8; 

DFZ 7-10,11 


9-12; А-4 


Gamma function 3-3 

Global variables 1-7 

Grade up and grade down 
А-1 

Greater than function 3-3; 
А-1 

Greater than or equal function 
3-3; 3-5; А-1 

)GRUUP 8-4 

Groups 8-1 

listing names of 

GRP 8-5 

GRPDOC 10-3 

)GRPS 8-4 


5-8; 


3-5; 


8-4 


Halted function 1-8,9 
Halting execution 1-9,10; 
Headers for functions 1-1 
changing 1-4 

HELLO 12-1 

Heterogeneous output 2- 
Histogram function 0-5 
HOW functions 10-2 
Hyperbolic fonctions 


c-2 


Identity elements 6-2 
ILLEGAL USER ACCESS А-5 
Immediate execution mode 0-2 
IMPLICIT ERROR 7-1; 7-6; А-1 
Indexed selection 2-6; 4-21 
Indexed specification 2-6; 
4-6; 11-3,4 
Indexed variables 2-6 
See also Indexed specification, 
Indexed selection. 
INDEX ERROR А-2 
Index generator function 5-6 
Index-of function 5-6; А-1 
Index origin 4-1; 7-6; 7-10; 
a- 


4-2; 


INDEX-3 


Indirect access files 7-7: 
9-5; 9-15 

Infinite values z-1 

Inner product 2-5; 6-4,5 

Input file specification p-2,3 

Input using quote-quad and guad 
1-10; 2-9,10; 7-16; С-1,2 

Inserting function lines 1-3 

Integer domain 7-9 

Integrity of files 9-16 

INTERRUPT А-1 

interrupt C-2 

Inverse of a matrix 5-23 

010 4-1; 7-6; 7-10; А-1 


Join function 5-5; 5-9,10 
Keying time 7-18 
KRONOS commands 12-1,5 


KRONOS error messages A-4,6 

Labels on statements 1-4; 
1-7,9; 2-9; 5-20; 7-11 

Laminate function 5-9 

largest record number 9-10 

Latent expression 7-14 

356 7-17 

Least squares 5-24 

left argument 2-7 

LENGTH ERROR 3-1; А-2 

Less than function 3-3; 3-5; 


А-1 

less than ог equal function 3-3; 
3-5; А-1 

JLIS 8-4 

[113 7-15 

libraries of workspaces 7-7: 
7-12,13: 7-15; 10-1,3 


Library liat (0578) 7-15 

IIMIT ERROR 5-21: А-2; B-l 

LIMITS command 12-2 

line 2-9 

linear equations 5-23,25 

Line correction 0-3 

Line editing 1-4 

LINE FEED 0-3; С-2 

Line timing control 7-12,13 

Listing coded files 9-17 

Listing user-defined tunctions 
1-4 

ts 2-7,9 

ts of names for system 
functions 7-6 


behavior of 1-7 
@eclaration of 1-1,3 
names of active 1-8,9; 7-17,1 
11-3 
Location counter (CAE) 7-17 
D£9cK 7-11,12; А-1 
Locked functions 1-10; 
3-18; 9-7 
LOCHED OBJECT А-2 
Locked variables 1-7; 
Logarithm 3-2 
Logical internal representation 
11-3; 11-5 
LONG 11-4 
lost space in files 


7-11,12 


9-10; 9-15 


CETIM 7-12,13; А-1 
ЫХ 7-14 
Hagnizude function 3-3 


Magnitude range for numbers Е-1 

Matrix 4-1 

Matrix divide 5-24,25; 7-7 

Matrix inverse 5-23,24; 7-7 

Matrix product 6-4,5 

Matrix transpose. see nonadic 
transpose 

Maximum field length 7-19; 11-3 
D-3 

Maximum function 3-2 

Membership function 5-7; А-1 

Memory space. See Storage requir 
ments, Field length. 


Minimum field length 7-19; 11-3 
2-3 
Minus, See Subtraction, Additive 


inverse, Negative symbol 
MIXSD PUNCTION A-3 
Mixed functions 5-1,25 


Mode for files 9-6,7; 12-4,5 
Modify mode 12-4 

Modulus. See Residue 

Monadic format function 5-21,22 


Monadic functions 2-4 
Monadic transpose 5-15,16 
Multiplication 3-2 


Name class (090) 2-4,5; 7-11; 
А-1 

HAMP IB USE А-3 

Name list (O¥Z} 7-11; А-1 


Name list for stored workspaces 
(DRAMES) 7-14 

Name lists for system functions 
7-6 

NAME NOT POUND А-3 


INDEX-4 


Nares 

ané spaces 2-1 

for files 9-5 

for workspaces 7-8 

lists of, for system functions 

7-6 

of tied files 
ONAMES 7-14; А-1 
NAND function 3-3 
Natural logarithm 
Dye 2-4,5; 7-11; 
Negative synbol 2-3 
Niladic branch 1-9; 
Nila@ic functions 2-4 
DSE 7-21; А-1 
NOR function 3-3 
Not equal function 
А-1 
function 3-3 
greater than function 
35; А-1 
less than function 
3-5; А-1 
Numbers of tied files 
Number system conversion 
numeric-constant 2-3 
Numeric conversion using format 

functions 3-21,23 


9-10 
3-2 
А-1 
2-7 
3-3; 3-5; 


NOT 
Not 3-3; 


Kot 3-3; 


9-10 
5-18 


Numeric output format B-l 
Numeric type 5-5 
Odometer order 4-3,4 


)OFF 8-4 

One origin 4-1 

Open definition 1-3 

Operating system error messages 


А-4,6 
GPERATOR DROP А-6 
Operators 2-5; 6-1 
Optimization of API programs 
11-1,6 


Ordering of array elements 4-3,5 


Order of evaluation 2-1; 2-6,7; 
4-6,7 
OR function 3-3 
origin 4-1; 7-6; 7-10; А-1 
ORIGIN. Sea (lO 
Outer product 2-5; 6-4 
Output 
control options 7-8,9 
conversion using format funct- 
ions 5-21,23 
efficiency 11-6 


file specification 
format of 3-1 
implicit 2-8; 


D-2,3 
Bel 


lists 2-9 

using quad and qucte quad 
Overriding line numbers 1-3 
Overstrike 9-4 
»OVb* А-6 
Page eject 7-9 
PARAMETER ERROR А-5 
PARITY ERROR А-5 
Passwords 7-7; 9-5,7: 12-4 
Pendent functions 1-8,9 
Per-element time 11-5 
Permanent files 9-5 
PERMIT command 12-5 
PP UTILITI ACTIVE А-5 
PHRASE NOT FOUN $ АЗ 
DPL 7-6; 
Plane coordinate 4-1 
PLOTFNS 10-1 
Plus function 3-2 
Positioning files 9-9; 9-12 
Position of a file 9-7,8 
Power functüon 3-2; 3-4 
СРР 7-6; 7-8: A-1,2 
PP ABORT А-6 

recision of calculations E- 


Preconversion 2-2 
Primitive functions 2-4 
Printer “Carriage control 7-9 


Printing precision (PP) 7- 
7-8; A-1,2 

Printing width (ОРУ) 2-10: 
7-8 

Print lines (DPI) 7-8; 7-8, 

Privacy of files 9-6,7 

Private files 7-7; 9-6 

Program libraries 7-13; 10- 

Prohibit prompt option 0-2 

Prompt suppression D-2 

Protected copy 8-3 

PSTATUS 9-10 

Public files 7-7; 9-6 

Public libraries 10-2 

DPW 2-10; 7-6; 7-8 

Quad input and output 1-10; 
7-16; C-1,2 

Quote quad input and output 
2-9,10; C-1,2 

Radices 5-28 

Randon link (077) 7-6; 7-10 

RANK ERROR 3-1; 7-1; А-2 

Rank of an array 4-l; 4-4 

Ravel function 4-2; 4-4,5 

Read mode 9-6; 9-14; 12-4 


INDEX-5 


2-9,10 


.13 


1 


7- 


3 


xead-modify node 9-6: 
12-4 
wciprocal 3-2 
ecord delete (FROZE) 
Record number largest 
Record numbers 9-6 
cords 9-1 
RECOVER command 9-15; 
Reduction 2-5; 6-1,2 
Regression coefficients 
Relational functions 3-3; 
al 
Remainder. See Residue 
Removing function lines 1-4 
Renumbering function lines 1-4 
Repositioning files 9-9; 9-12 
Represent function 5-19,20; 
7-7 
Reshape function 
Residuals 5-24,25 
Residue function 3-3,4 
Response time 11-2 
Restarting execution 
Result variable 1-1; 
2-5 
Returning files 
RETURN key 
Reverse function 5-14 
Revising keyboard entries 
Rewind 9-12,13 
DRL 7-6; 7-9; А-1 
Roll function 3-3; 7-10; 
Rotate function 5-14,15 
Row coordinate 4-2 


12-1,2 


5-24,25 
3-5; 


4-2,3 


1-9 
1-7: 


9-20 


0-4 


А-1 


ZSAVE А-1 
SAVE 
Scalar 


7-13: 
8-3 
arrays 4-1 
Scalar extension 
Scalar functions 3-1,5 
Scan functions 2-5; 6-3,4 
Security of files 9-6,7 
Seed. See URL 
Selectric terminals 
6-1,2; D-1 
Semantics for APL statements 
2-1,10 
Semiprivate files 7-7; 9-6 
Sequenzial file operations 
9-7 


5-5 


0—: 


Session variables 7-6 
SETTL command 12-2,3 
Setup time 11-5 

Snape of an array 4-3,4 


Shared files 9-14 


Shifted output option D-2 


SHORT 11-4 


Shortcuts in function editing l- 
)31 1-8,9; 8-4 

Sí DAMAGE 1-9,10; 7-11; А-3 
Signing off 0-7; 7-19 

Signing on 0-1,2; C-2 

Sign-on characters С-2 

Signum function 3-2 

Sine function 3-3; 3-5 

Dsrv 7-17,18 

)SIV 1-8,9; 8-4 

Size function 4-2; 4-4 

Sizes of files 7-17; 9-9; 9-14 


Skip record, file, or to end 
9-12,13 

Sorting 5-8 

SOURCE documentation 10-3 

Space requirements, see Storage 


requirements 
Spaces 2-1 
Specification 0-3; 2-6,7; 4-25 
4-6 
Square root, see Power function 
Standards for programs 10-1,3 
State indicator 1-8,9; 7-17,18; 
8-4 
State indicator damage 1-9,10; 
7-11; А-3 
Statement labels 2-9 
and execute function 5-20; 7- 
and line renumbering 1-4 
in SIV display 1-8,5 
localization of 1-7 
Statistical package 10-1 
Status of files (FSTATUS) 9-10 
DSZOP 7-12; А-1 
Stop controls 1-10; 7-12 


Stopping function execution 
c= z 
Storage limits 12-3 
Storage requirements 
in files 9-15 
in workspaces 
Stored files 9-5 
Stored workspazes 7- 
Submitting batch jobs. 
Subtraction function 
Suspended functions 
2-1,8 
057 2-2; 7-7; 11-4 
Symbol table size 12-4 
SYNTAX ERROR А-1 
Syntax for APL statements 2 
)S7STEM 8-4. See also OTH 


1-9, 


11-2,4 


see 
3-2 
1-8,9; 


1,10 


INDEX-6 


6 


„15 


11 


12: 


SYSTEM ABORT А-6 
System commands (ISF) 


PINZD FUNCTION А-З 
versity of Mass., sign-on 


2-2; 2-7; 8-1, procedure for 0-1,2; C-2 
System functions 2- unprotected copy 8-3 
System variables 2-5; 7-1,19  Unquote function. See Execute 
function 
Table lookup 6-5 untie for files $-10; 9-14 
таке function 5-12,13 Unused space 9-10; 9-15 
Tangent function 3-3; 3-5 User-defined functions l-l; 
Teletype terminals C-2; D-1,2 2-4 
Terminal node (Ц?М) 7-19 User number. See Account number 
Terminal type 7-6; D-1 
Tied files 9-4 Vacart list elements 
*TIME LIMIT* error 12-2,4 Validation limits 12-2 
TIME LIMIT message A-5 VALUE E3ROR 2-4,6; А-2 
Times function 3-2 vaiue 2-6 
Time stamp (075) 7-6; 7-18 Variable names 2-5 
Timing controls 1-10 Variables 0-3 
Timings, table of 11-6 nares of defined 7-11; 8-4 
Оти 7-19 )VARS 8-4 
О?ВАСЕ 7-12; А-1 vector 0-3: 4-1 
race controls 1-10; 7-12; Visual fidelity 0-3 
А-1 
TRACK LIMIT А-5 DRA 7e 11-3: А-2 
transpose functions 5-15,18: Weight: 
sats. ВА WIDTH. see ПРИ 
DTRAP 716,17; 9-7 Working area 7-6: 
Trap line 7-16,17 Workspace 0-6 
Drs 7-6; 7-18 name (O¥sry} 7-13 
077 7-16 names, forms for 7-8 
TTY33 Terminal type 5-1 size. see Field length 
TTY383 Terminal type D-2 Write mode 9-6,7; 9-14; 12-4 
Type of an array 5-5 WROKG TYPE FILE А-4 
Type of files 7-15 WSPNS workspace 10-1; 11-4 
WS FULL 1-4; 7-19; 11-3: А-2 
ушсор 8-3 28878 7-13; А-1 
TADEX-7 


